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:

Parameter	Type	Description
`userOps`	string	Comma-separated route types. Use `tx` for OpenRouter transaction routes. Also supports `deposit` and `cex-withdraw`.
`originChainId`	string	Required for `tx` and `deposit`. Source chain ID.
`destinationChainId`	string	Destination chain ID.
`inputToken`	string	Source token address.
`inputAmount`	string	Source amount in smallest units.
`outputToken`	string	Destination token address.
`receiverAddress`	string	Destination receiver.
`userAddress`	string	Required for `tx`. Source wallet that will sign the transaction.

Optional query parameters:

Parameter	Type	Description
`slippage`	number string	Slippage percent, for example `0.5`.
`feeBps`	number string	Integrator fee in basis points. Supports decimals. Requires `feeTakerAddress`.
`feeTakerAddress`	string	Fee recipient. Required when `feeBps` is set.
`includeProvider`	string	Comma-separated provider IDs to include. Same-chain maps to DEX IDs; cross-chain maps to bridge IDs.
`excludeProvider`	string	Comma-separated provider IDs to exclude. Cannot overlap with `includeProvider`.
`refuel`	`true` or `false`	Optional refuel request. Defaults to `false`.
`destinationPayload`	hex string	Destination payload. Requires `destinationGasLimit`.
`destinationGasLimit`	string	Gas limit for `destinationPayload`. Requires `destinationPayload`.
`refundAddress`	string	Required for `deposit` and `cex-withdraw`.
`exchange`	string	Required for `cex-withdraw`, for example `coinbase` or `binance`.

Active same-chain DEX provider IDs:

Provider ID	Display name
`zeroxv2`	0x v2
`openocean`	OpenOcean
`kyberswap`	KyberSwap
`magpie`	Magpie
`bebopPmm`	Bebop PMM
`tempoStablecoin`	Tempo Stablecoin
`ondoGm`	Ondo GM

Cross-chain bridge provider IDs:

Provider ID	Display name
`across`	Across
`arbitrum-native`	Arbitrum Native Bridge
`bob-gateway`	BOB Gateway
`celer`	Celer
`cctp-v2`	CCTP v2 (fast)
`cctp-v2-slow`	CCTP v2 (slow / canonical)
`gaszip`	GasZip
`gnosis-native`	Gnosis Native Bridge
`hypercore`	Hypercore Deposit
`kyo-ag`	Kyo AG
`mayan`	Mayan
`native-op-stack`	Native OP Stack Bridge
`near-intents`	Near Intents
`oft`	OFT (LayerZero)
`polygon-native`	Polygon Native Bridge
`relay`	Relay
`rhinofi`	RhinoFi
`scroll-native`	Scroll Native Bridge
`tempo-stablecoin-dex`	Tempo 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:

Field	Description
`quoteId`	Stable route ID. Use it for status polling. For OpenRouter tx routes this is the on-chain request hash.
`expiresAt`	Unix timestamp after which the quote should be discarded.
`output.amount`	Expected destination output amount after applicable fees.
`output.minAmountOut`	Minimum acceptable destination output amount.
`routeTags`	Ranking labels added by Swap V3: `SUGGESTED`, `FASTEST`, `MAX_OUTPUT`.
`approval`	Present for ERC20 inputs. Approve this spender before sending `txData`.
`txData.kind`	Transaction type. OpenRouter EVM routes use `evm_tx`.
`txData.object`	Transaction payload to send from `userAddress`.
`statusCheck`	Suggested polling endpoint and cadence.

Swap V3 Status

Request

GET /v3/swap/status?quoteId=<quoteId>

Parameters:

Parameter	Required	Description
`quoteId`	Yes	Quote ID returned by `/v3/swap/quote`.
`includeQuoteDetails`	No	Set 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:

Status	Meaning
`PENDING`	Quote or route has not started.
`IN_PROGRESS`	Source transaction is known, destination completion is pending.
`COMPLETED`	Route is complete.
`FAILED`	Route failed.
`EXPIRED`	Quote or execution window expired.
`REFUNDED`	Funds were refunded.

Execution Flow

Request quotes from /v3/swap/quote with userOps=tx.
Select a route. Prefer routeTags or compare output.valueInUsd, estimatedTime, and gasFee.
Check quote freshness with expiresAt.
If approval is present, approve approval.spenderAddress for approval.amount of approval.tokenAddress.
Submit the route transaction from userAddress. For an EVM route, send txData.object as the transaction.
Poll status with the returned quoteId.
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.

INTRODUCTION

USE CASES

FEATURES

RESOURCES

SECURITY

MONETIZATION

LEGAL

Openrouter swap v3 user reference

Swap V3 User Reference

Endpoint Selection

Common Token and Amount Rules

Swap V3 Quote

Request

Same-Chain OpenRouter Swap Example

Cross-Chain OpenRouter Bridge Example

Response Shape

Swap V3 Status

Request

Response Shape

Execution Flow

Fees

Validation and Error Notes

Implementation Notes for Integrators

​Swap V3 User Reference

​Endpoint Selection

​Common Token and Amount Rules

​Swap V3 Quote

​Request

​Same-Chain OpenRouter Swap Example

​Cross-Chain OpenRouter Bridge Example

​Response Shape

​Swap V3 Status

​Request

​Response Shape

​Execution Flow

​Fees

​Validation and Error Notes

​Implementation Notes for Integrators

Swap V3 User Reference

Endpoint Selection

Common Token and Amount Rules

Swap V3 Quote

Request

Same-Chain OpenRouter Swap Example

Cross-Chain OpenRouter Bridge Example

Response Shape

Swap V3 Status

Request

Response Shape

Execution Flow

Fees

Validation and Error Notes

Implementation Notes for Integrators