> This page is for Taurus PROTECT, version v3.56.
> For other versions, use one of these documentation indexes:
> - v3.58 (default): https://taurushq.ferndocs.com/protect-capital/v3.58/llms.txt
> - v3.56: https://taurushq.ferndocs.com/protect-capital/v3.56/llms.txt
> - v3.54: https://taurushq.ferndocs.com/protect-capital/v3.54/llms.txt
> - v3.52: https://taurushq.ferndocs.com/protect-capital/v3.52/llms.txt
> - v3.50: https://taurushq.ferndocs.com/protect-capital/v3.50/llms.txt
> - v3.48: https://taurushq.ferndocs.com/protect-capital/v3.48/llms.txt
> - v3.46: https://taurushq.ferndocs.com/protect-capital/v3.46/llms.txt
> - v3.44: https://taurushq.ferndocs.com/protect-capital/v3.44/llms.txt
> - v3.42: https://taurushq.ferndocs.com/protect-capital/v3.42/llms.txt
> - v3.40: https://taurushq.ferndocs.com/protect-capital/v3.40/llms.txt
> - v3.38: https://taurushq.ferndocs.com/protect-capital/v3.38/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server.

# List addresses

GET https://your-protect-instance.example.com/api/rest/v1/addresses

This endpoint returns a list of addresses

Reference: https://taurushq.ferndocs.com/protect-capital/reference/addresses/list

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Query parameters

- `currency` (string, optional) — Filter on IDs or symbols of the currency
- `query` (string, optional)
- `limit` (long, optional)
- `offset` (long, optional)
- `scoreProvider` (string, optional) — Deprecated. Use scoreFilter instead.
- `scoreInBelow` (string, optional) — Deprecated. Use scoreFilter instead.
- `scoreOutBelow` (string, optional) — Deprecated. Use scoreFilter instead.
- `scoreExclusive` (boolean, optional) — Deprecated. Use scoreFilter instead.
- `onlyPositiveBalance` (boolean, optional) — Set this parameter to true to get only addresses with a positive unconfirmed balance
- `sortBy` (string, optional) — Set this parameter to select the type on which you want to sort.The types accepted yet are: BALANCE and ADDRESSID
- `sortOrder` (string, optional) — Set this parameter to ASC to get the addresses sorted in ascending order or DESC to get them in descending order.
- `balanceBelow` (string, optional) — Filter addresses and keep only addresses with a balance below the threshold.
- `balanceAbove` (string, optional) — Filter addresses and keep only addresses with a balance above the threshold.
- `walletId` (string, optional)
- `customerId` (string, optional)
- `coinfirmScoreGreater` (string, optional) — Deprecated. Use scoreFilter instead.
- `chainalysisScoreGreater` (string, optional) — Deprecated. Use scoreFilter instead.
- `tagIDs` (list of string, optional) — Filter addresses with a 'OR' combination of tag IDs
- `blockchain` (string, optional)
- `network` (string, optional)
- `addressIds` (list of string, optional) — Filter addresses with a list of address IDs.
- `nfts` (string, optional) — One of [exclude, include, only] depending on whether you want to include addresses of type NFTs (or you want only those). Filtering will be performed after pagination: `totalItems` won't represent the number of addresses with this filter but can be used in combination with `offset`.
- `addresses` (list of string, optional) — Filter addresses with a list of blockchain addresses (hashes).The blockchain needs to be specified when using this filter.
- `scoreFilter.scoreProvider` (string, optional) — Specify the score provider to filter on, or empty.Each provider has associated filter parameters that can be set.Supported values: `scorechain`, `coinfirm`, `chainalysis`, `elliptic`, `trmlabs`
- `scoreFilter.scorechainFilters.scoreInBelow` (string, optional) — Filter addresses under a Scorechain incoming score threshold.
- `scoreFilter.scorechainFilters.scoreOutBelow` (string, optional) — Filter addresses under a Scorechain outgoing score threshold.
- `scoreFilter.scorechainFilters.scoreExclusive` (boolean, optional) — By default when both Scorechain scores scoreInBelow and scoreOutBelow are provided, it returns the addresses matching (scoreInBelow AND scoreOutBelow). When scoreExclusive is set to true, it will return the addresses matching (scoreInBelow OR scoreOutBelow).
- `scoreFilter.coinfirmFilters.scoreGreater` (string, optional) — Filter addresses with a Coinfirm C-score above threshold.
- `scoreFilter.chainalysisFilters.scoreGreater` (string, optional) — Filter addresses with a Chainalysis risk score above threshold.
- `scoreFilter.ellipticFilters.scoreGreater` (string, optional) — Filter addresses with an Elliptic risk score above threshold.
- `scoreFilter.trmlabsFilters.scoreGreater` (string, optional) — Filter addresses with an TRM Labs risk score above threshold.
- `attributeFiltersJson` (string, optional) — A JSON representation of a list of AttributeFilter objects. The filters are combined with an attributeFiltersOperator ('OR' by default). Each AttributeFilter can use different comparison operators: `=` (default if not specified), `<>` (not equal), `>` (greater than), `>=` (greater than or equal), `<` (less than), `<=` (less than or equal)
- `attributeFiltersOperator` (string, optional) — Specifies how attribute filters are combined. Accepted values: 'OR' (default), 'AND'.
- `includeDisabledAddresses` (string, optional) — One of [exclude, include, only] depending on whether you want to include disabled addresses (or you want only those). Filtering will be performed after pagination: `totalItems` won't represent the number of addresses with this filter but can be used in combination with `offset`.
- `includeUntagged` (string, optional) — One of [exclude, include, only] depending on whether you want to include untagged addresses (or you want only those). Optional field with default value as "include"

## Response

### 200

A successful response.

- `result` (list of tgvalidatordAddress, optional)
- `totalItems` (string, optional)
- `offset` (string, optional) — The offset to get the next page. Note: the value is not always the same as the number of elements returned.

## Errors

### 400 Bad Request Error

Bad Request: indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing)

- `any`

### 401 Unauthorized Error

Unauthorized: indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource

- `any`

### 403 Forbidden Error

Forbidden: indicates that the server understands the request but refuses to authorize it

- `any`

### 404 Not Found Error

Not Found: indicates that the server cannot find the requested resource

- `any`

### 500 Internal Server Error

Internal Server Error: indicates that the server encountered an unexpected condition that prevented it from fulfilling the request

- `any`

### 503 Service Unavailable Error

Service Unavailable: indicates that the server is not ready to handle the request.

- `any`

## Types

### tgvalidatordAddress

- `id` (string, optional) — uint64; Unique identifier for the address.
- `walletId` (string, optional) — uint64; Unique identifier for the wallet associated with the address (parent wallet)
- `seed` (string, optional) — Which seed in the HSM to use for address generation..
- `currency` (string, optional) — Currency associated with the address (e.g., ETH, BTC). For a list of enabled currencies, query the [currencies endpoint](https://docs.taurushq.com/protect-capital/reference/walletservice_getcurrencies).
- `addressPath` (string, optional) — The derivation path for the address, used to generate the address from the seed.
- `addressIndex` (string, optional) — uint64; Index used for address generation. Required for derivation paths.
- `address` (string, optional) — The actual address generated for the wallet.
- `alternateAddress` (string, optional) — An alternate address that can be used for transactions, if available.
- `comment` (string, optional) — An optional comment associated with the address.
- `label` (string, optional) — A user-friendly label for the address (e.g., 'Deposit Address'). Displayed as `Name` in the UI.
- `customerId` (string, optional) — Identifier for the customer associated with the address.
- `nonce` (string, optional) — uint64; The current nonce of the address. A nonce is a 32-bit (or 4-byte) number used to prevent replay attacks.
- `balance` (tgvalidatordBalance, optional)
- `signature` (string, optional) — Signature associated with the address.
- `scores` (list of tgvalidatordScore, optional) — Risk score related to the address, pulled from external reputation services. (e.g., Scorechain, Chainalysis, etc...).
- `attributes` (list of tgvalidatordAddressAttribute, optional) — Additional attributes and metadata associated with the address.
- `linkedWhitelistedAddressIds` (list of string, optional) — List of whitelisted address IDs that are linked to this address.
- `creationDate` (datetime, optional) — The date and time when the address was created.
- `updateDate` (datetime, optional) — The date and time when the address was last updated.
- `walletInfo` (tgvalidatordWalletInfo, optional)
- `disabled` (boolean, optional) — Indicates whether the address is disabled.
- `currencyInfo` (tgvalidatordCurrency, optional)
- `canUseAllFunds` (boolean, optional) — Indicates whether all funds in the address can be used.
- `externalAddressId` (string, optional) — An optional external identifier for the address.
- `status` (string, optional) — Status of address creation. Creating status is used for asynchronous address creation. Value is one of `created`, `creating, `signed`, `observed`, or `confirmed`.

### tgvalidatordBalance

- `totalConfirmed` (string, optional) — Total confirmed balance in the smallest currency unit (e.g., WEI for ETH).
- `totalUnconfirmed` (string, optional) — Total balance including unconfirmed transactions in smallest currency unit (e.g., WEI). Exceeds totalConfirmed when transactions are pending confirmation. Equal to confirmed balance when all funds are confirmed.
- `availableConfirmed` (string, optional) — Available confirmed balance that is ready to be spent or used.
- `availableUnconfirmed` (string, optional) — Available balance including unconfirmed transactions.
- `reservedConfirmed` (string, optional) — Confirmed reserved balance that is set being held for specific purposes, such as another pending transactions.
- `reservedUnconfirmed` (string, optional) — Reserved unconfirmed balance that is not yet fully validated.

### tgvalidatordScore

- `id` (string, optional)
- `provider` (string, optional)
- `type` (string, optional)
- `score` (string, optional)
- `updateDate` (datetime, optional)

### tgvalidatordAddressAttribute

- `key` (string, optional) — A key that Protect assigns to the attribute. E.g., `legacyAddress` `has_any_transactions`, etc...
- `value` (string, optional) — The value of the attribute.
- `id` (string, optional) — Unique identifier for the attribute.
- `contentType` (string, optional) — Content type of the attribute value. Usually `text/plain.`
- `owner` (string, optional) — Owner of the attribute. Most commonly `system` or `user`.
- `type` (string, optional) — A Protect generated attribute type. E.g., `transaction_info`, `tag`, etc...
- `subtype` (string, optional) — A Protect generated subtype. Not commonly used but can be used to further classify the attribute.
- `isfile` (boolean, optional) — Indicates whether the attribute is a file.

### tgvalidatordWalletInfo

- `id` (string, optional)
- `balance` (tgvalidatordBalance, optional)
- `currency` (string, optional)
- `coin` (string, optional)
- `name` (string, optional)
- `container` (string, optional)
- `seed` (string, optional)
- `accountPath` (string, optional)
- `isOmnibus` (boolean, optional)
- `creationDate` (datetime, optional)
- `updateDate` (datetime, optional)
- `customerId` (string, optional)
- `comment` (string, optional)
- `disabled` (boolean, optional)
- `blockchain` (string, optional)
- `addressesCount` (string, optional)
- `currencyInfo` (tgvalidatordCurrency, optional)
- `attributes` (list of tgvalidatordWalletAttribute, optional)
- `network` (string, optional)
- `visibilityGroupID` (string, optional)
- `externalWalletId` (string, optional) — An optional external identifier for the wallet.

### tgvalidatordCurrency

- `name` (string, optional) — Name of the currency.
- `symbol` (string, optional) — Shorthand symbol for the currency.
- `coinTypeIndex` (string, optional) — Index used to identify the coin type in BIP44. (e.g. Bitcoin is 0, Ethereum is 60).
- `blockchain` (string, optional) — The Blockchain the currency is associated with, (e.g. ETH, BTC).
- `isToken` (boolean, optional) — Indicates if the currency is a token (e.g., ERC-20).
- `isERC20` (boolean, optional) — DEPRECATED: use tokenInfo.tokenType == ERC20 instead.
- `decimals` (string, optional) — Number of decimal places the currency uses (e.g. 18 for ETH).
- `contractAddress` (string, optional) — Smart contract address if currency is a smart contract (e.g. ERC-20.).
- `hasStaking` (boolean, optional) — Indicates if the currency supports staking.
- `isUTXOBased` (boolean, optional) — Indicates if the currency is UTXO-based (e.g. Bitcoin).
- `isAccountBased` (boolean, optional) — Indicates if the currency is account-based (e.g. Ethereum).
- `isFiat` (boolean, optional) — Indicates if the currency is a fiat currency (e.g. CHF, EUR, USD).
- `isFA12` (boolean, optional) — DEPRECATED: use tokenInfo.tokenType == FA12 instead.
- `isFA20` (boolean, optional) — DEPRECATED: use tokenInfo.tokenType == FA2 instead.
- `isNFT` (boolean, optional) — Indicates if the currency represents a Non-Fungible Token (NFT).
- `enabled` (boolean, optional) — Indicates if the currency is enabled in the current tenant.
- `id` (string, optional) — Unique identifier of the currency.
- `displayName` (string, optional) — Display name for the currency, (e.g. Ethereum, Bitcoin).
- `type` (string, optional) — Type of the currency. Can be `token`, `fiat`, `native` , or `signet`.
- `wlcaId` (string, optional) — White listed contract address id associated with the currency.
- `network` (string, optional) — Network or environment the currency is used on (e.g. 'mainnet', 'testnet').
- `tokenID` (string, optional) — Unique id for the token, if applicable (e.g. for NFTs).
- `logo` (string, optional) — Currency logo in Data URI scheme. Base 64 encoded. (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==).
- `tokenInfo` (tgvalidatordTokenInfo, optional) — Token-specific details for a Currency. Present only when the currency is a token.

### tgvalidatordWalletAttribute

- `key` (string, optional)
- `value` (string, optional)
- `id` (string, optional)
- `contentType` (string, optional)
- `owner` (string, optional)
- `type` (string, optional)
- `subtype` (string, optional)
- `isfile` (boolean, optional)

### tgvalidatordTokenInfo

Token-specific details for a Currency. Present only when the currency is a token.

- `tokenType` (enum, optional) — Token standard of a currency; set only when it is a token. Replaces isERC20 (6), isFA12 (15), isFA20 (16).
  - Allowed values: `TOKEN_TYPE_ERC20`, `TOKEN_TYPE_ERC721`, `TOKEN_TYPE_ERC1155`, `TOKEN_TYPE_CRYPTO_PUNKS`, `TOKEN_TYPE_FA2`, `TOKEN_TYPE_FA12`, `TOKEN_TYPE_ASA`, `TOKEN_TYPE_COSMOS_BANK`, `TOKEN_TYPE_CW20`, `TOKEN_TYPE_XLM_ASSET`, `TOKEN_TYPE_SOL_TOKEN`, `TOKEN_TYPE_SOL_TOKEN_2022`, `TOKEN_TYPE_ICRC1`, `TOKEN_TYPE_HEDERA_TOKEN`, `TOKEN_TYPE_HEDERA_NFT`, `TOKEN_TYPE_CANTON_UTILITY`, `TOKEN_TYPE_TRC20`, `TOKEN_TYPE_CIP56`, `TOKEN_TYPE_XRP_ASSET`

## Examples

**Response**

```json
{
  "result": [
    {
      "id": "string",
      "walletId": "string",
      "seed": "string",
      "currency": "string",
      "addressPath": "string",
      "addressIndex": "string",
      "address": "string",
      "alternateAddress": "string",
      "comment": "string",
      "label": "string",
      "customerId": "string",
      "nonce": "string",
      "balance": {
        "totalConfirmed": "string",
        "totalUnconfirmed": "string",
        "availableConfirmed": "string",
        "availableUnconfirmed": "string",
        "reservedConfirmed": "string",
        "reservedUnconfirmed": "string"
      },
      "signature": "string",
      "scores": [
        {
          "id": "string",
          "provider": "string",
          "type": "string",
          "score": "string",
          "updateDate": "2024-01-15T09:30:00Z"
        }
      ],
      "attributes": [
        {
          "key": "string",
          "value": "string",
          "id": "string",
          "contentType": "string",
          "owner": "string",
          "type": "string",
          "subtype": "string",
          "isfile": true
        }
      ],
      "linkedWhitelistedAddressIds": [
        "string"
      ],
      "creationDate": "2024-01-15T09:30:00Z",
      "updateDate": "2024-01-15T09:30:00Z",
      "walletInfo": {
        "id": "string",
        "balance": {
          "totalConfirmed": "string",
          "totalUnconfirmed": "string",
          "availableConfirmed": "string",
          "availableUnconfirmed": "string",
          "reservedConfirmed": "string",
          "reservedUnconfirmed": "string"
        },
        "currency": "string",
        "coin": "string",
        "name": "string",
        "container": "string",
        "seed": "string",
        "accountPath": "string",
        "isOmnibus": true,
        "creationDate": "2024-01-15T09:30:00Z",
        "updateDate": "2024-01-15T09:30:00Z",
        "customerId": "string",
        "comment": "string",
        "disabled": true,
        "blockchain": "string",
        "addressesCount": "string",
        "currencyInfo": {
          "name": "string",
          "symbol": "string",
          "coinTypeIndex": "string",
          "blockchain": "string",
          "isToken": true,
          "isERC20": true,
          "decimals": "string",
          "contractAddress": "string",
          "hasStaking": true,
          "isUTXOBased": true,
          "isAccountBased": true,
          "isFiat": true,
          "isFA12": true,
          "isFA20": true,
          "isNFT": true,
          "enabled": true,
          "id": "string",
          "displayName": "string",
          "type": "string",
          "wlcaId": "string",
          "network": "string",
          "tokenID": "string",
          "logo": "string",
          "tokenInfo": {
            "tokenType": "TOKEN_TYPE_ERC20"
          }
        },
        "attributes": [
          {
            "key": "string",
            "value": "string",
            "id": "string",
            "contentType": "string",
            "owner": "string",
            "type": "string",
            "subtype": "string",
            "isfile": true
          }
        ],
        "network": "string",
        "visibilityGroupID": "string",
        "externalWalletId": "string"
      },
      "disabled": true,
      "currencyInfo": {
        "name": "string",
        "symbol": "string",
        "coinTypeIndex": "string",
        "blockchain": "string",
        "isToken": true,
        "isERC20": true,
        "decimals": "string",
        "contractAddress": "string",
        "hasStaking": true,
        "isUTXOBased": true,
        "isAccountBased": true,
        "isFiat": true,
        "isFA12": true,
        "isFA20": true,
        "isNFT": true,
        "enabled": true,
        "id": "string",
        "displayName": "string",
        "type": "string",
        "wlcaId": "string",
        "network": "string",
        "tokenID": "string",
        "logo": "string",
        "tokenInfo": {
          "tokenType": "TOKEN_TYPE_ERC20"
        }
      },
      "canUseAllFunds": true,
      "externalAddressId": "string",
      "status": "string"
    }
  ],
  "totalItems": "string",
  "offset": "string"
}
```

**SDK Code**

```python
import requests

url = "https://your-protect-instance.example.com/api/rest/v1/addresses"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://your-protect-instance.example.com/api/rest/v1/addresses';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://your-protect-instance.example.com/api/rest/v1/addresses"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://your-protect-instance.example.com/api/rest/v1/addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://your-protect-instance.example.com/api/rest/v1/addresses")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://your-protect-instance.example.com/api/rest/v1/addresses', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://your-protect-instance.example.com/api/rest/v1/addresses");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://your-protect-instance.example.com/api/rest/v1/addresses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```