Skip to main content
The Socket Swap V3 API routes same-chain swaps, cross-chain swaps, deposit addresses and non-EVM transfers through a single quote-and-execute flow. This guide covers the end-to-end integration and how to submit the returned transaction on each chain family. For full request parameters and response schemas, use the API Reference tab.

​
Setup

Use the production base URL with your credentials:
Send x-api-key and affiliate headers. For testing without credentials, use https://public-backend.socket.tech. See Get API Access for the full breakdown.

​
Choose your flow

The userOps query parameter on /v3/swap/quote selects the route type: This guide covers userOps=tx. For the deposit flow (including the activationRequired step), see the Deposit Addresses guide.

​
Core flow

1

Get a quote

Request routes from /v3/swap/quote with userOps=tx. Same-chain when originChainId === destinationChainId, cross-chain otherwise.
Each route carries a quoteId, an expiresAt, an optional approval, the txData to submit, and a statusCheck block. userAddress is required for tx routes. See the quote endpoint for the complete field list.
2

Select a route

Rank routes with routeTags (SUGGESTED, FASTEST, MAX_OUTPUT, MIN_INPUT) or compare output.valueInUsd, estimatedTime, and gasFee. Discard quotes past expiresAt.
3

Approve (ERC20 only)

When the route includes an approval object, the ERC20 input must be approved to approval.spenderAddress (usually Socket’s AllowanceHolder, not the final bridge or DEX) for at least approval.amount.The quote does not read your on-chain allowance, so approval is present whenever a route could need it. Check the current allowance yourself and only send an approval transaction when it is below approval.amount. Native-token inputs return no approval.
4

Submit the transaction

Submit the route’s txData from userAddress. The txData.kind field tells you how — see Submitting by chain below.
Do not rebuild calldata client-side. Always submit the returned txData.object exactly as provided.
5

Poll status

Poll GET /v3/swap/status?quoteId={quoteId} (cadence suggested in statusCheck) until a terminal status: COMPLETED, FAILED, EXPIRED, or REFUNDED. PENDING and IN_PROGRESS are non-terminal.

​
Submitting by chain

The quote response returns execution data as txData.kind (a discriminator) plus txData.object. Submit according to the kind:

​
EVM

​
Solana

kind: "svm_instructions" returns { instructions, lookupTables, signers }. Resolve the lookup tables, compile a v0 TransactionMessage, sign with the user’s wallet, and send with connection.sendRawTransaction. kind: "svm_versioned_tx" returns a serialized VersionedTransaction string in object.data — deserialize, add the user signature, and broadcast.
For gasless same-chain Solana swaps, pass solanaSponsorAddress on the quote. The sponsor covers transaction fees and ATA rent. Solana origin only.

​
Tron

kind: "tron_tx" returns EVM-style { to, data, value } where to is the contract (often a hex-encoded Tron address). Build the call with tronWeb.transactionBuilder.triggerSmartContract, sign, and broadcast. Supported tokens/routes are provider-specific (for example USDT and USDT0 mesh routes).

​
Sui

kind: "sui" returns object.data with transactionBytes (transaction-kind bytes only) plus quoteId, coinType, packageId, and vaultObjectId. Rebuild with Transaction.fromKind(transactionBytes), set the sender, gas owner, budget, and payment coin, then build, sign, and execute. Sui-origin routes settle through the RFQ vault (stablecoin USDSUI).

​
Bitcoin

kind: "btc_deposit" returns { depositAddress, amount, orderHash? }. Construct and broadcast a native Bitcoin transaction sending amount satoshis to depositAddress; include orderHash as an OP_RETURN output when present. Bitcoin is a deposit-style origin — there is no signed contract call. Set refundAddress to a BTC address for BTC-origin routes.

​
Advanced flags

Use quoteType=EXPECTED_OUTPUT or EXACT_OUTPUT with outputAmount to target a destination amount instead of fixing the input. The response echoes quoteType, and matching routes may carry the MIN_INPUT tag. Default flow is EXACT_INPUT + inputAmount.
Set simulatedQuotesRequired=true for same-chain DEX quotes to simulate routes on-chain before returning them — reverting quotes are dropped and amounts reflect simulation. Simulated routes expose output.isSimulated and may set output.quotedAmount (pre-adjustment amount). Pair with includeQuoteRejections=true to see filtered providers. Not available with output quote types.
Set incognito=true with userOps=tx to quote only privacy-capable providers (houdini, changenow). refundAddress is required. EVM and Solana only; not compatible with output quote types. Same-chain same-token is allowed for wallet-to-wallet transfers. See Incognito Mode.
By default the AllowanceHolder requires the signing wallet to also be the caller of AllowanceHolder.exec. If you route through an intermediate contract, the call reverts with CallerNotSignedUser. Set contractCaller to that contract’s address to authorize it. Only applies to userOps=tx.
Attach destinationPayload (with destinationGasLimit) to execute calldata on the destination chain after bridging. Track execution via isDestPayloadExecuted on the status response. See Destination Payload.
Set feeBps and feeTakerAddress together to charge a fee. feeBps must be between 0 and 10000. The client-facing output amount is already net of fees. For direct bridge no-swap routes, fees are taken on the input side.

​
Provider filtering

Restrict routes with includeProvider / excludeProvider (comma-separated public IDs; they cannot overlap). For the live catalog and full ID list, call GET /v3/swap/providers — see Supported Providers.

Deposit Addresses

Accept deposits from any chain

Destination Payload

Execute calldata on the destination chain

Chain Support

See all supported networks

API Reference

Full request and response schemas