A typed v2 API built for real integrations

The v2 REST API is the surface real integrations needed. Filter and sort every list, page through results, and track transactions through asynchronous settlement. An idempotency key makes a route safe to replay only where its contract says so. The v2 API is served at /api/v2, and the v1 API stays frozen at /api/v1.

The v1 API answered a simple need: call an endpoint, get a result. Real integrations needed more.

They needed to ask for the 50 most recent holders of one token, retry a mint after a dropped connection without minting twice, and decide whether a call waits for on-chain settlement or returns immediately. The v2 API is built for that, on a typed contract the SDK generates a client from.

Filter and sort every listCopy Anchor Link

List endpoints accept structured filters using JSON:API bracket notation. A filter with no operator uses the field's default; an explicit operator goes in a second bracket. Supported operators are eq, ne, gt, gte, lt, lte, iLike (case-insensitive match), inArray, notInArray, isEmpty, and isNotEmpty. An inArray filter accepts up to 100 values.

GET /api/v2/tokens?filter[name][iLike]=Northwind&sort=-createdAt&page[limit]=50&page[offset]=0

Sorting accepts a sort field with an optional - prefix for descending order, or the flat sortBy and sortDirection aliases. Use one parameter dialect per request. Default ordering depends on the resource. Each resource restricts sortBy to its own typed set of columns, so a sort request that an endpoint cannot honor is rejected at the contract rather than silently ignored.

Page through results predictablyCopy Anchor Link

Pagination is offset based. Pass limit (default 50, maximum 200) and offset, and every collection response returns the links you need to walk the set without computing offsets yourself.

Pagination documents the collection envelope and links.

Asynchronous first, synchronous when you askCopy Anchor Link

A blockchain write takes real time to settle. The platform submits it, waits for it to be included in a block, and confirms it, and that takes seconds, or longer when the network is busy. An API that blocks the caller's connection until the chain confirms is fragile: a dropped request loses the result, a slow block ties up the client, and a stuck transaction hangs the call. So transaction routes on the v2 API are asynchronous first.

When you submit a transaction, the platform accepts it, queues it durably, and returns 202 Accepted with a status URL straight away. The instruction then runs in the background on the durable transaction engine, so it survives a dropped connection, a restart, or a slow chain. You poll the status URL until the operation reaches a terminal state.

The returned handle identifies the transaction request and its status URL. Read the V2 API schema for the complete response.

Switch to synchronous when you want the result inlineCopy Anchor Link

For a short, interactive flow where you need the result before continuing, ask the platform to wait. Send Prefer: wait=N to hold the response for up to N seconds, clamped to between 5 and 99, while the operation settles. A synchronous wait never changes the outcome. It only changes whether the platform returns the result inline or hands back a status URL to poll.

• If the operation settles within the budget, the platform returns 200 OK with the settled response.
• If the budget elapses first, it degrades to the same 202 Accepted status URL, and you poll from there.

The platform echoes the directives it honored in the Preference-Applied response header.

Send the same request body and idempotency key when adding a synchronous wait. See Idempotency and async settlement for the response-timing contract.

The SDK waits by defaultCopy Anchor Link

The current TypeScript SDK requests a 15-second settlement wait by default. Set settlementTimeoutMs to choose another bound, or set it to zero to request an immediate pending handle.

Use a synchronous wait for short interactive flows. Use the asynchronous path for long-running operations, batch jobs, or any flow that already tracks transaction status and events. Pair Prefer with Idempotency-Key so a retry after a degraded 202 attaches to the original instruction instead of submitting a new one.

Retry mutations safelyCopy Anchor Link

The hardest part of any write API is the uncertain response: the request left, but the reply never arrived. Send an Idempotency-Key header with a mutation and a retry is safe. The platform recognizes the key, runs the operation once, and returns the original result on the retry instead of executing it again. For transaction writes, the deduplication identity includes the sending wallet, chain, and key. Generate a unique key per instruction, store it next to your own job ID, and reuse it only when retrying the same request. Change the payload, route, or method and you create a new instruction with a new key.

Idempotency and async settlement gives the request contract and retention rules.

Control identity and wallet per requestCopy Anchor Link

A few headers let one API key act precisely without a separate credential per actor.

Errors your code can branch onCopy Anchor Link

Every v2 error response carries the same structured error envelope as the SDK and CLI. The envelope includes a stable DALP-NNNN id, a category that classifies the failure, a retryable boolean, a message for display, a why explaining the cause, and a fix describing the next step. When the platform knows how long to wait, it includes retryAfterSeconds. Calling code branches on the category and retryability, never on a parsed prose string. See the error code reference and error handling.

v1 stays availableCopy Anchor Link

The v2 API is the default, and /api redirects to /api/v2. The v1 API is not removed. It stays frozen at /api/v1 with its request and response shapes unchanged, so existing integrations keep working without a migration deadline. Its specification remains available at /api/v1/spec.json. Plan a V2 migration against its current schemas and endpoint coverage.

Get started with the API → · Request headers →