curl --request POST \
  --url https://api.dfns.io/wallets/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "q": "treasury",
  "limit": 50
}
'

{
  "items": [
    {
      "wallet": {
        "id": "wa-1f04s-lqc9q-xxxxxxxxxxxxxxxx",
        "network": "Ethereum",
        "address": "0x00e3495cf6af59008f22ffaf32d4c92ac33dac47",
        "name": "trading hot wallet",
        "signingKey": {
          "id": "key-6ece3-9l565-xxxxxxxxxxxxxxxx",
          "scheme": "ECDSA",
          "curve": "secp256k1",
          "publicKey": "e2375c8c9e87bfcd0be8f29d76c818cabacd51584f72cb2222d49a13b036d84d3d",
          "storeId": "store-2ab1c-4d5e6-xxxxxxxxxxxxxxxx"
        },
        "status": "Active",
        "dateCreated": "2023-04-14T20:41:28.715Z",
        "custodial": true,
        "tags": []
      },
      "matchedAsset": {
        "kind": "Native",
        "decimals": 123,
        "balance": "<string>",
        "symbol": "<string>",
        "verified": true
      },
      "assets": [
        {
          "kind": "Native",
          "decimals": 123,
          "balance": "<string>",
          "symbol": "<string>",
          "verified": true
        }
      ]
    }
  ],
  "nextPageToken": "<string>",
  "partial": "capped"
}

Search Wallets

Searches the wallets of your organization: find a wallet from an identifier you already have, from a word in its name, or from a token it holds, and narrow the results with filters.

How q matches

q is compared with five kinds of identifier, then with wallet names. Unless sort is set, results come in the order below.

Identifiers, matched exactly:

If `q` is	Example	You get
a wallet id	`wa-1f04s-lqc9q-xxxxxxxxxxxxxxxx`	that wallet
an external id	`cust-00412`	that wallet, followed by the exact and prefix name matches
a vault id	`vlt-2b9kq-7m4rt-xxxxxxxxxxxxxxxx`	the wallets of that vault
an address, in any case	`0x00e3495cf6af59008f22ffaf32d4c92ac33dac47`	the wallets at that address
the hash of a transfer or transaction made from one of your wallets	`0x8e88793607610a83798eb5ec6dde861f3e459c7e4a22e78b0d2e675b86d0d1e7`	the wallet that made it

A wallet id, vault id, address or hash match returns only those wallets, with no name matches.

Names, ignoring case and accents. For a wallet named Trading Hot Wallet:

Exact: the name is the text, as with trading hot wallet.
Prefix: the name starts with the text, as with trad.
Loose: the name contains the text, or matches it with a small typo, as with wallet or tradng. Loose matches are left out when an identifier matches, when a wallet has the exact name, and when matching is precise.

Without q, every wallet that passes the filters is returned.

Filters all apply together. filters.asset returns the wallets holding a positive balance of a token. Archived wallets are left out unless filters.statuses includes Archived.

Order. By default, results are ranked by relevance when q is set, by the filtered token’s balance (largest first) with an asset filter, and newest first otherwise. sort orders by name or dateCreated instead. With an asset filter, the only accepted sort is assetBalance.

Pages. A page holds up to limit wallets (50 by default, at most 500). For the next page, send the same body again with paginationToken set to the nextPageToken of the previous response, and keep the rest of the body unchanged: a token only continues the order it was issued for. See Pagination.

Incomplete results. A very broad search on a large organization can reach an internal cap. The response then carries partial: 'capped': the results are a subset of the matches and paging ends early. Narrow the search with a longer term or another filter to get a complete answer.

Errors (see Error codes):

400 with details.kind SearchTimeout: the search could not finish in time. The message says what to change: a longer search term, fewer filters, or ordering by date instead of name.
400 with details.kind UnsupportedAssetSelector: filters.asset.token is not supported yet. Use filters.asset.symbol.
503 with details.kind DependencyUnavailable: search is briefly unavailable. Retry the request.

Requires the Wallets:Read permission. Not available to end users of delegated wallets, because a search spans the whole organization.

POST

wallets

curl --request POST \
  --url https://api.dfns.io/wallets/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "q": "treasury",
  "limit": 50
}
'

{
  "items": [
    {
      "wallet": {
        "id": "wa-1f04s-lqc9q-xxxxxxxxxxxxxxxx",
        "network": "Ethereum",
        "address": "0x00e3495cf6af59008f22ffaf32d4c92ac33dac47",
        "name": "trading hot wallet",
        "signingKey": {
          "id": "key-6ece3-9l565-xxxxxxxxxxxxxxxx",
          "scheme": "ECDSA",
          "curve": "secp256k1",
          "publicKey": "e2375c8c9e87bfcd0be8f29d76c818cabacd51584f72cb2222d49a13b036d84d3d",
          "storeId": "store-2ab1c-4d5e6-xxxxxxxxxxxxxxxx"
        },
        "status": "Active",
        "dateCreated": "2023-04-14T20:41:28.715Z",
        "custodial": true,
        "tags": []
      },
      "matchedAsset": {
        "kind": "Native",
        "decimals": 123,
        "balance": "<string>",
        "symbol": "<string>",
        "verified": true
      },
      "assets": [
        {
          "kind": "Native",
          "decimals": 123,
          "balance": "<string>",
          "symbol": "<string>",
          "verified": true
        }
      ]
    }
  ],
  "nextPageToken": "<string>",
  "partial": "capped"
}

Authentication

✅ Tenant User (TenantUser)
✅ Organization User (CustomerEmployee)
❌ End User (EndUser)
✅ Service Account

Required Permissions

Wallets:Read: Always required.

Authorizations

Authorization

string

header

required

Bearer Token: Used to authenticate API requests. More details how to generate the token: Authentication flows

Body

application/json

string

Text to search for. A wallet id, address, external id, transaction hash or vault id resolves to its wallets. Any other text matches wallet names: an exact name first, then names starting with the text, then looser matches such as a word inside a name or a typo.

Maximum string length: 200

sort

object

Result order. Omitted, results are ranked by relevance when q is set, by the filtered token balance with an asset filter, and newest first otherwise. assetBalance requires an asset filter, and an asset filter accepts no other sort.

Show child attributes

limit

integer

Maximum number of wallets to return, up to 500. Defaults to 50.

Required range: 1 <= x <= 500

paginationToken

string

Opaque token used to retrieve the next page. Returned as nextPageToken from the previous request.

Minimum string length: 1

includeAssets

enum<string>

Inline each wallet's assets: 'native' returns its native asset only, 'verified' adds its verified tokens. Omit to return none.

Available options:

native,

verified

matching

enum<string>

How widely to match. 'broad' (the default when omitted) matches identifiers and names, and also looks inside names and tolerates typos. 'precise' matches identifiers and names only: an exact id, an exact name, or the start of a name. It skips the fuzzy work, so it is markedly faster on a large org, but it is not a guarantee against the time limit: a search that also carries several filters can still exceed it.

Available options:

precise,

broad

filters

object

Narrows the results. A wallet is returned only if it matches every filter set here.

Show child attributes

Response

200 - application/json

Success

items

object[]

required

The matches on this page, in result order.

Show child attributes

nextPageToken

string

Present when more results exist. Send it as paginationToken, with the rest of the request unchanged, to get the next page.

partial

enum<string>

Present only as 'capped', and only when an internal cap decided what this search could reach. The results are a subset of the matches and paging will end before the real end of the match set. Do not read them as the closest matches: depending on which branch answered, the cap keeps either the alphabetically first matches or an arbitrary sample of them. Absent means the page is complete. Narrow the search with a longer term or one more filter to get an exact answer.

Available options:

capped

API Authorization

Identity & Access Management

Wallets & Transactions

Management

Webhooks

Search Wallets

Authentication

Required Permissions

Authorizations

Body

Response