Skip to main content

​
Swap V3 User Reference

Last verified against the Socket Swap V3 swagger: 2026-06-10. This reference covers the user-facing Swap V3 endpoints:
  • GET /v3/swap/quote: Swap V3 quote API. userOps=tx maps to OpenRouter direct routes.
  • GET /v3/swap/status: Swap V3 status API.
Use relative paths in this document with the API base URL for the target environment.

​
Endpoint Selection

Use /v3/swap/quote to fetch executable transaction routes, deposit-address routes, and CEX withdraw routes in one normalized route model. OpenRouter direct routes currently support:
  • Same-chain swaps when originChainId === destinationChainId.
  • Cross-chain bridge routes when originChainId !== destinationChainId.

​
Common Token and Amount Rules

  • inputAmount is a string in the smallest token unit for EVM-style chains.
  • The native token address is 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.
  • EVM addresses are normalized to lowercase by the API.
  • receiverAddress must be valid for the destination chain.
  • userAddress is required for OpenRouter transaction routes.
  • Same-chain quotes reject identical inputToken and outputToken.

​
Swap V3 Quote

​
Request

GET /v3/swap/quote
Required query parameters:
ParameterTypeDescription
userOpsstringComma-separated route types. Use tx for OpenRouter transaction routes. Also supports deposit and cex-withdraw.
originChainIdstringRequired for tx and deposit. Source chain ID.
destinationChainIdstringDestination chain ID.
inputTokenstringSource token address.
inputAmountstringSource amount in smallest units.
outputTokenstringDestination token address.
receiverAddressstringDestination receiver.
userAddressstringRequired for tx. Source wallet that will sign the transaction.
Optional query parameters:
ParameterTypeDescription
slippagenumber stringSlippage percent, for example 0.5.
feeBpsnumber stringIntegrator fee in basis points. Supports decimals. Requires feeTakerAddress.
feeTakerAddressstringFee recipient. Required when feeBps is set.
includeProviderstringComma-separated provider IDs to include. Same-chain maps to DEX IDs; cross-chain maps to bridge IDs.
excludeProviderstringComma-separated provider IDs to exclude. Cannot overlap with includeProvider.
refueltrue or falseOptional refuel request. Defaults to false.
destinationPayloadhex stringDestination payload. Requires destinationGasLimit.
destinationGasLimitstringGas limit for destinationPayload. Requires destinationPayload.
refundAddressstringRequired for deposit and cex-withdraw.
exchangestringRequired for cex-withdraw, for example coinbase or binance.
Active same-chain DEX provider IDs:
Provider IDDisplay name
zeroxv20x v2
openoceanOpenOcean
kyberswapKyberSwap
magpieMagpie
bebopPmmBebop PMM
tempoStablecoinTempo Stablecoin
ondoGmOndo GM
Cross-chain bridge provider IDs:
Provider IDDisplay name
acrossAcross
arbitrum-nativeArbitrum Native Bridge
bob-gatewayBOB Gateway
celerCeler
cctp-v2CCTP v2 (fast)
cctp-v2-slowCCTP v2 (slow / canonical)
gaszipGasZip
gnosis-nativeGnosis Native Bridge
hypercoreHypercore Deposit
kyo-agKyo AG
mayanMayan
native-op-stackNative OP Stack Bridge
near-intentsNear Intents
oftOFT (LayerZero)
polygon-nativePolygon Native Bridge
relayRelay
rhinofiRhinoFi
scroll-nativeScroll Native Bridge
tempo-stablecoin-dexTempo Stablecoin DEX

​
Same-Chain OpenRouter Swap Example

curl -G "$BASE_URL/v3/swap/quote" \
  -H "affiliate: YOUR_AFFILIATE_ID" \
  --data-urlencode "userOps=tx" \
  --data-urlencode "originChainId=42161" \
  --data-urlencode "destinationChainId=42161" \
  --data-urlencode "inputToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831" \
  --data-urlencode "outputToken=0x912ce59144191c1204e64559fe8253a0e49e6548" \
  --data-urlencode "inputAmount=10000000" \
  --data-urlencode "userAddress=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
  --data-urlencode "receiverAddress=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
  --data-urlencode "slippage=0.5" \
  --data-urlencode "includeProvider=zeroxv2,kyberswap"

​
Cross-Chain OpenRouter Bridge Example

curl -G "$BASE_URL/v3/swap/quote" \
  -H "affiliate: YOUR_AFFILIATE_ID" \
  --data-urlencode "userOps=tx" \
  --data-urlencode "originChainId=42161" \
  --data-urlencode "destinationChainId=10" \
  --data-urlencode "inputToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831" \
  --data-urlencode "outputToken=0x0b2c639c533813f4aa9d7837caf62653d097ff85" \
  --data-urlencode "inputAmount=10000000" \
  --data-urlencode "userAddress=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
  --data-urlencode "receiverAddress=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
  --data-urlencode "slippage=0.5" \
  --data-urlencode "includeProvider=across,cctp-v2"

​
Response Shape

{
  "originChainId": 42161,
  "destinationChainId": 10,
  "userAddress": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "receiverAddress": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "input": {
    "token": {
      "chainId": 42161,
      "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "logoURI": "https://..."
    },
    "amount": "10000000",
    "priceInUsd": 1,
    "valueInUsd": 10
  },
  "routes": [
    {
      "userOp": "tx",
      "quoteId": "0x...",
      "expiresAt": 1760000000,
      "output": {
        "token": {
          "chainId": 10,
          "address": "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "logoURI": "https://..."
        },
        "amount": "9855420",
        "minAmountOut": "9806142",
        "priceInUsd": 1,
        "valueInUsd": 9.85542
      },
      "estimatedTime": 60,
      "slippage": 0.5,
      "suggestedSlippage": 0.5,
      "routeTags": ["SUGGESTED", "MAX_OUTPUT"],
      "routeDetails": {
        "name": "Across",
        "logoURI": "https://media.socket.tech/bridges/across.png",
        "dexDetails": null,
        "bridgeDetails": {
          "protocol": {
            "name": "across",
            "displayName": "Across",
            "icon": "https://media.socket.tech/bridges/across.png"
          },
          "inputTokenAddress": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
          "outputTokenAddress": "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
          "amountIn": "10000000",
          "amountOut": "9855420",
          "minAmountOut": "9806142",
          "slippage": 0.5
        }
      },
      "approval": {
        "spenderAddress": "0x...",
        "amount": "10000000",
        "tokenAddress": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
        "userAddress": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266"
      },
      "txData": {
        "kind": "evm_tx",
        "object": {
          "chainId": 42161,
          "to": "0x...",
          "data": "0x...",
          "value": "0"
        }
      },
      "gasFee": {
        "gasToken": {},
        "gasLimit": "650000",
        "gasPrice": "100000000",
        "estimatedFee": "65000000000000",
        "feeInUsd": 0.01
      },
      "statusCheck": {
        "endpoint": "https://dedicated-backend.socket.tech/v3/swap/status?quoteId=0x...",
        "method": "GET",
        "intervalSec": 5,
        "maxDurationSec": 600
      }
    }
  ]
}
Important route fields:
FieldDescription
quoteIdStable route ID. Use it for status polling. For OpenRouter tx routes this is the on-chain request hash.
expiresAtUnix timestamp after which the quote should be discarded.
output.amountExpected destination output amount after applicable fees.
output.minAmountOutMinimum acceptable destination output amount.
routeTagsRanking labels added by Swap V3: SUGGESTED, FASTEST, MAX_OUTPUT.
approvalPresent for ERC20 inputs. Approve this spender before sending txData.
txData.kindTransaction type. OpenRouter EVM routes use evm_tx.
txData.objectTransaction payload to send from userAddress.
statusCheckSuggested polling endpoint and cadence.

​
Swap V3 Status

​
Request

GET /v3/swap/status?quoteId=<quoteId>
Parameters:
ParameterRequiredDescription
quoteIdYesQuote ID returned by /v3/swap/quote.
includeQuoteDetailsNoSet to true to include stored quote row details in the response.
The v3 status endpoint looks up execution state by quoteId.

​
Response Shape

{
  "quoteId": "0x...",
  "userOp": "tx",
  "status": "IN_PROGRESS",
  "statusCode": "PENDING",
  "origin": {
    "chainId": 42161,
    "status": "COMPLETED",
    "txHash": "0x...",
    "timestamp": null,
    "userAddress": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
    "input": []
  },
  "destination": {
    "chainId": 10,
    "status": "PENDING",
    "txHash": null,
    "timestamp": null,
    "receiverAddress": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
    "output": []
  },
  "routeDetails": {
    "name": "Across",
    "logoURI": "https://media.socket.tech/bridges/across.png"
  },
  "refund": null
}
Status values:
StatusMeaning
PENDINGQuote or route has not started.
IN_PROGRESSSource transaction is known, destination completion is pending.
COMPLETEDRoute is complete.
FAILEDRoute failed.
EXPIREDQuote or execution window expired.
REFUNDEDFunds were refunded.

​
Execution Flow

  1. Request quotes from /v3/swap/quote with userOps=tx.
  2. Select a route. Prefer routeTags or compare output.valueInUsd, estimatedTime, and gasFee.
  3. Check quote freshness with expiresAt.
  4. If approval is present, approve approval.spenderAddress for approval.amount of approval.tokenAddress.
  5. Submit the route transaction from userAddress. For an EVM route, send txData.object as the transaction.
  6. Poll status with the returned quoteId.
  7. Continue polling until the route reaches a terminal status.

​
Fees

Integrator fees are set with feeBps and feeTakerAddress. Rules:
  • feeBps and feeTakerAddress must be provided together.
  • feeBps must be greater than 0 and at most 10000.
  • For direct DEX routes, fees can be taken from input or output depending on the OpenRouter fee resolution.
  • For direct bridge no-swap routes, fees are forced to the input side.
  • The client-facing output amount is already net of applicable fees.
Swap V3 exposes the net output and execution data. It does not expose a separate affiliate fee object on tx routes.

​
Validation and Error Notes

Common 400 errors:
  • Missing userOps for /v3/swap/quote.
  • Missing originChainId for userOps=tx.
  • Missing userAddress for userOps=tx.
  • Missing refundAddress for userOps=deposit or userOps=cex-withdraw.
  • Missing exchange for userOps=cex-withdraw.
  • Invalid slippage.
  • Invalid or unsupported chain ID.
  • destinationPayload without destinationGasLimit, or the reverse.
  • feeBps without feeTakerAddress, or the reverse.
  • Provider listed in both include and exclude filters.
Quote responses can return an empty route list when providers fail to quote, the route is unsupported, OpenRouter is not deployed for the origin chain in the active environment, or filters exclude all providers.

​
Implementation Notes for Integrators

  • OpenRouter EVM routes usually ask the user to approve the AllowanceHolder contract, not the final bridge or DEX.
  • The transaction to is usually the AllowanceHolder. The OpenRouter call is wrapped inside the returned calldata.
  • Use quoteId exactly as returned. It is used for status lookup and source transaction recording.
  • Do not rebuild calldata client-side. Use the returned txData.
  • Do not send expired quotes.
  • For same-chain swaps, routeDetails.dexDetails is populated in Swap V3 when route metadata is available.
  • For cross-chain routes, routeDetails.bridgeDetails describes the bridge leg. If there is an origin swap leg, routeDetails.dexDetails may also be present.