Build Swap

Build the current signable step for a swap. The API persists the swap submission, publishes the execution intent, and returns either a ready-to-sign payload or an async polling handle. Use a fresh quoteId and routeId from POST /quote; stale quote bindings return 410 QUOTE_EXPIRED. Swagger does not auto-fill those fields from the previous quote response, so you must paste the fresh values when testing in the docs UI. The gateway does not emit placeholder wallet payloads. If the execution surface for the active step is not configured, the endpoint returns 503.

Endpoint: POST /api/v1/swap/build Auth: Required (Authorization: Bearer YOUR_API_KEY)

Headers

Header	Required	Description
Idempotency-Key	No	Optional opaque dedupe token. If omitted, the gateway generates one automatically. Leave it blank for one-off Swagger or curl calls. Send your own UUIDv4 or ULID only when retrying the exact same payload and you need retry-safe dedupe. Allowed characters: A-Z, a-z, 0-9, ., _, :, -. Max 200 chars.

Request body

Field	Type	Required	Description
quoteId	string	Yes	Quote ID from POST /quote
routeId	string	Yes	Route ID from the selected quote route
recipient	string	No	Destination wallet address
userAddress	string	No	Optional wallet address used by the signing surface
permitType	string	No	eip2612, permit2, or approve
permitDeadline	integer	No	Permit deadline in ms
permitSignature	object	No	Expanded v, r, s permit signature
permitSignatureCompact	object	No	Compact r, vs permit signature
permit2	object	No	Permit2 payload
waitForTxRequestMs	integer	No	Bounded wait window before falling back to async polling

Example

curl -X POST 'https://api.gateway.zert.com/api/v1/swap/build' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "quoteId": "REPLACE_WITH_QUOTE_ID_FROM_POST_QUOTE",
    "routeId": "REPLACE_WITH_ROUTE_ID_FROM_SELECTED_ROUTE",
    "recipient": "0x1234567890123456789012345678901234567890",
    "waitForTxRequestMs": 300
  }'

Leave Idempotency-Key blank for one-off Swagger or curl calls. Paste a fresh quoteId and routeId from the previous POST /quote response. If you need retry-safe dedupe, send your own key only when retrying the exact same payload. The SDK and Postman collection can generate one automatically.

Example sync response

{
  "data": {
    "swapId": "92714c81-38ec-4782-8624-0f56f526a9fd",
    "mode": "sync",
    "nextAction": "sign",
    "signing": {
      "step": { "current": 1, "total": 3 },
      "expiresAtMs": 1776977916667,
      "readyAtMs": 1776977796877,
      "clientHints": {
        "recommendedWallet": "phantom",
        "network": "solana",
        "action": "swap"
      },
      "payload": {
        "type": "solana",
        "transaction": "AQAAAA..."
      }
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-04-23T20:56:04.937Z"
  }
}

Example async response

{
  "data": {
    "swapId": "8933a4cd-a08d-43b7-a63f-d7c1a53fdbe8",
    "mode": "async",
    "nextAction": "poll",
    "pollAfterMs": 250,
    "signing": {
      "step": null,
      "expiresAtMs": null,
      "readyAtMs": null
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-04-23T20:56:04.937Z"
  }
}

Responses

Code	Description
200	A signable payload is ready immediately
202	Accepted, but the first signable step is still building
400	Invalid request
401	Unauthorized
409	Current tx request is invalid for signing
410	Quote expired; request a new quote and retry
503	PG or Kafka unavailable, execution plan not yet readable, or signing surface unavailable

Zert APIsapi.gateway.zert.com

Zert API — Build Swap