VASP Search

VASP search finds the counterparty VASPs of the API key's environment: both sides of its transfers, and the VASPs that wallet discovery resolved for them. Each VASP appears once, under its latest name, sorted by name.

Endpoint

Method	Endpoint	Scope
GET	/api/v2/vasps/search	transfers:read

Request

curl "$COVALENT_URL/api/v2/vasps/search?q=north&limit=20" \
  -H "x-api-key: $COVALENT_API_KEY"

Parameter	Description
q	Matched anywhere in a VASP's ID or in any name it has had, at most 100 characters. An empty q finds nothing.
limit	Results per page, a positive whole number, default 20. Anything over 50 is read as 50.
cursor	meta.cursor of the previous page.

Response

{
  "data": [
    {
      "id": "did:web:northgate.example",
      "name": "Northgate",
      "source": "transfer_history"
    },
    {
      "id": "did:web:northwind.example",
      "name": "Northwind Markets",
      "source": "transfer_history"
    }
  ],
  "meta": {
    "apiVersion": 2,
    "timestamp": "2026-10-09T12:00:00.000Z",
    "query": "north",
    "count": 2,
    "cursor": "eyJrIjoibm9ydGh3aW5kIG1hcmtldHMiLCJpZCI6ImRpZDp3ZWI6bm9ydGh3aW5kLmV4YW1wbGUifQ",
    "hasMore": true,
    "limit": 2
  }
}

Field	Description
id	The VASP's ID: a DID, or a provider's identifier.
name	Its latest name, else its ID.
source	transfer_history when one of the environment's transfers names the VASP; otherwise how wallet discovery resolved it (discovery, or the resolution method recorded).
meta.query	The search as run, trimmed.
meta.count	How many VASPs are on this page.
meta.cursor	Send it as ?cursor= for the next page; null on the last page. The search's cursor is opaque, and only the search reads it.
meta.hasMore	Whether another page follows.
meta.limit	The page size used.

Searches read every transfer of the environment, so they are limited per company and environment, for all of the company's API keys together. Over the limit, a search is refused with 429 RATE_LIMITED and a Retry-After header. Only a search with a non-empty q counts.

Errors

Status	Code	When
400	INVALID_QUERY	limit is not a positive whole number, or q is over 100 characters.
400	INVALID_CURSOR	The cursor is not one this search handed out.
429	RATE_LIMITED	Too many searches. Wait for Retry-After.