> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Openrouter swap v3 user reference

# 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

```http theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "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

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.