Track a Swap

After you execute a swap, track it to a terminal state. You can poll the swap status endpoint with the quote’s quoteId, or subscribe to live WebSocket updates keyed by the wallet address. Both reach the same outcome — poll when a request/response loop is enough, subscribe when you want push updates without polling.

quote.quoteId and the top-level id identify different resources. quoteId tracks the saved swap quote — it is the {id} for GET /v2/swap/status/{id}. The top-level id is the Action id — use it with GET /actions/{id} and to correlate WebSocket action_update events.

Poll swap status

Track onramp, offramp, swap, and yield quote flows with the Swap v2 status endpoint, using the quote.quoteId from the quote response.

GET /v2/swap/status/{quoteId}

curl -sS \
  -H "x-api-key: $PODS_API_KEY" \
  "$PODS_API_BASE_URL/v2/swap/status/8ef5685b-280d-4b01-8a02-97cd05fe1d35"

Successful response (trimmed to the fields you branch on):

{
  "quoteId": "8ef5685b-280d-4b01-8a02-97cd05fe1d35",
  "provider": "uniswap",
  "status": "pending",
  "originChain": "ethereum",
  "destinationChain": "ethereum",
  "originAddress": "0xb794F5eA0ba39494cE839613fffBA74279579268",
  "destinationAddress": "0xb794F5eA0ba39494cE839613fffBA74279579268"
}

Poll until status is terminal (fulfilled, expired, failed, or refunded).

Status	Meaning	Terminal
`pending`	Payment has not been detected yet, or the quote is still waiting for confirmation.	No
`confirmed`	Payment was detected and output settlement is not final yet.	No
`processing`	Output settlement is in progress.	No
`fulfilled`	Final success state.	Yes
`expired`	Quote or fiat payment expired before payment was detected.	Yes
`failed`	Operational failure. Show an error and route to support or retry.	Yes
`refunded`	Refund flow finished, when applicable.	Yes

Already have the mined transaction hash? Report it with POST /v2/swap/status/{id}/update/{txHash} so the API processes it immediately instead of waiting for indexer webhooks, then poll GET /v2/swap/status/{id} for the outcome. Resubmissions are idempotent.

WebSocket updates (recommended)

Subscribe to live updates instead of polling. Connect, subscribe to the wallet channel, and listen for action_update events.

wss://api.pods.finance/updates

{ "type": "subscribe", "channel": "<walletAddress>" }

Listen for action_update events where action.id matches the top-level id from the quote/execution response:

Status	Meaning
`PENDING`	Awaiting settlement
`SUCCESS`	Settlement completed
`FAILED`	Settlement failed
`REFUNDED`	Refund completed

Re-subscribe on reconnect. Alternatively, use your customer webhook (ACTION_UPDATE events) — set a per-quote webhookURL on the quote to override the default endpoint.

Action execution status

For on-chain execution progress (as opposed to quote settlement), poll the Action by the top-level id:

GET /actions/{id}

Use this when you need the execution/Action state; use GET /v2/swap/status/{quoteId} for quote settlement. Reference:

Overview

Guides

Integrations

Agents

Poll swap status

WebSocket updates (recommended)

Action execution status

​Poll swap status

​WebSocket updates (recommended)

​Action execution status

Poll swap status

WebSocket updates (recommended)

Action execution status