Full swap flow

This guide walks through the public swap flow: quote, build, poll when needed, sign externally, submit the signed artifact, and optionally track the resulting transaction.

Step 1: Request a quote

Call POST /quote with the source chain, destination chain, input token, output token, and amount.

Step 2: Build the current signing step

Call POST /swap/build with the quoteId and selected routeId. Swagger does not auto-fill those fields from the Step 1 response, so paste the fresh values yourself when testing in the docs UI.

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

If you want retry-safe dedupe on direct HTTP calls, send your own Idempotency-Key. Swagger does not carry the prior quote response into this request. SDK and Postman flows can generate the idempotency key automatically, and Postman also captures the live quoteId and routeId for you.

The response is either:

• mode: "sync" with a ready-to-sign payload in data.signing
• mode: "async" with pollAfterMs telling you when to poll GET /swap/{swapId}/signing

If the signing surface for the active step is not configured, POST /swap/build returns 503 instead of a placeholder transaction.

Postman does not sign transactions. Hand the payload to the external wallet or signer you control.

Step 3: Poll the signing endpoint

If the build response is async, poll until the signing payload is ready:

curl -X GET 'https://api.gateway.zert.com/api/v1/swap/your-swap-id/signing' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Step 4: Submit the signed artifact

After the wallet signs the payload, submit the signed artifact:

curl -X POST 'https://api.gateway.zert.com/api/v1/swap/your-swap-id/signing' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "rawTx": "0x_signed_tx_from_external_wallet"
  }'

If the flow has multiple signing steps, keep polling the same endpoint until the next payload is ready.

Step 5: Track the transaction

Once you have a transaction hash, use GET /status/transaction/{txHash}?chainRef=... to verify on-chain progress.

Step	Endpoint	Purpose
1	POST /quote	Request a quote
2	POST /swap/build	Build the current signing step
3	GET /swap/{swapId}/signing	Poll when signing is async
4	POST /swap/{swapId}/signing	Submit the signed artifact
5	GET /status/transaction/{txHash}	Verify the on-chain transaction

See Request Quote, Build Swap, Get Signing Status, Submit Signed Artifact, and Get Transaction Status for full request and response details.