> ## 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.

# Socket v2 API → Socket v3 API

> Migrate from the legacy Socket API (v2) to the Socket Swap V3 API.

```txt LLM prompt — copy and paste into your coding agent theme={null}
Migrate my Socket API v2 integration to the Socket Swap V3 API.
Use https://docs.socket.tech/llms-full.txt for full context and follow https://docs.socket.tech/integrate/migration-guide-v2.
```

The Socket Swap V3 API (`/v3/swap`) replaces the legacy Socket API (`/v2`). The new API is simpler — a single quote call returns ready-to-send transaction data. No server-side route sessions, no multi-step build flow.

The base URL also changes:

| | v2 | v3 |
| - | - | - |
| Base URL | `https://api.socket.tech/v2` | `https://backend.socket.tech/v3/swap` |

## What changed at a glance

| | v2 (Legacy) | v3 (New) |
| - | - | - |
| Quote | `GET /v2/quote` | `GET /v3/swap/quote` |
| Tx data | `POST /v2/route/start` + `GET /v2/route/build-next-tx` | Included in quote response |
| Status | `GET /v2/route/prepare` | `GET /v3/swap/status` |
| Approval check | `GET /v2/approval/check-allowance` | `route.approval` object in quote response |
| Approval tx data | `GET /v2/approval/build-tx` | Build client-side using `route.approval` |
| Auth header | `API-KEY` | `x-api-key` + `affiliate` |
| Route ID | `activeRouteId` | `quoteId` |

***

## Execution flow

**Before (v2):**

1. `GET /v2/quote` → pick a route
2. `POST /v2/route/start` → register the route, get `activeRouteId`
3. `GET /v2/approval/check-allowance` → check if approval needed
4. `GET /v2/approval/build-tx` → build approval tx
5. `GET /v2/route/build-next-tx?activeRouteId=...` → get tx calldata
6. Submit the transaction on-chain
7. `GET /v2/route/prepare?activeRouteId=&userTxIndex=&txHash=` → report tx hash
8. Repeat steps 5–7 for multi-tx routes

**After (v3):**

1. `GET /v3/swap/quote` → get routes with txData included
2. If `route.approval` is present, approve `approval.spenderAddress` for `approval.amount`
3. Submit `route.txData.object` on-chain
4. Poll `GET /v3/swap/status?quoteId=...` until terminal status

All routes are single-transaction. No server-side session required.

***

## Parameter mapping

### Headers

| v2 | v3 |
| - | - |
| `API-KEY: <key>` | `x-api-key: <key>` |
| — | `affiliate: <affiliate-id>` (required) |

### Query parameters

| v2 param | v3 param | Notes |
| - | - | - |
| `fromChainId` | `originChainId` | |
| `toChainId` | `destinationChainId` | |
| `fromTokenAddress` | `inputToken` | |
| `toTokenAddress` | `outputToken` | |
| `fromAmount` | `inputAmount` | |
| `userAddress` | `userAddress` | Unchanged |
| `recipient` | `receiverAddress` | |
| `defaultBridgeSlippage` / `defaultSwapSlippage` | `slippage` | Single unified slippage param |
| `includeDexes` / `includeBridges` | `includeProvider` | Comma-separated |
| `excludeDexes` / `excludeBridges` | `excludeProvider` | Comma-separated |
| `feePercent` | `feeBps` | **Unit change:** percent → basis points. `0.5%` becomes `50` |
| `feeTakerAddress` | `feeTakerAddress` | Unchanged |
| — | `userOps` | **Required.** Use `tx` for standard routes |

<Note>
  `singleTxOnly`, `maxUserTxs`, `uniqueRoutesPerBridge`, `disableSwapping`,
  `bridgeWithGas`, `bridgeWithInsurance`, `isContractCall`, and `showAutoRoutes`
  are not supported in v3.
</Note>

***

## Approval

In v2 you called two separate endpoints to check and build approval transactions. In v3, the quote response tells you everything you need:

```json theme={null}
"approval": {
  "spenderAddress": "0x...",
  "amount": "1000000",
  "tokenAddress": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "userAddress": "0x..."
}
```

If `approval` is present, approve `spenderAddress` for `amount` of `tokenAddress` before submitting. If `approval` is `null`, no approval is needed.

***

## Status

**Before:**

```
GET /v2/route/prepare?activeRouteId=<id>&userTxIndex=<idx>&txHash=<hash>
```

**After:**

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

Poll until you see a terminal status:

| Status | Meaning |
| - | - |
| `PENDING` | Not yet started |
| `IN_PROGRESS` | Source tx seen, destination pending |
| `COMPLETED` | Done |
| `FAILED` | Failed |
| `EXPIRED` | Quote window expired |
| `REFUNDED` | Funds refunded |

***

## Quick example

**v2 request:**

```bash theme={null}
curl "https://api.socket.tech/v2/quote?fromChainId=42161&toChainId=8453&fromTokenAddress=0xaf88d...&toTokenAddress=0x8335...&fromAmount=1000000&userAddress=0x123...&recipient=0x123...&feePercent=0.5&feeTakerAddress=0xabc..." \
  -H "API-KEY: <key>"
```

**v3 equivalent:**

```bash theme={null}
curl "https://backend.socket.tech/v3/swap/quote?originChainId=42161&destinationChainId=8453&inputToken=0xaf88d...&outputToken=0x8335...&inputAmount=1000000&userAddress=0x123...&receiverAddress=0x123...&userOps=tx&feeBps=50&feeTakerAddress=0xabc..." \
  -H "x-api-key: <key>" \
  -H "affiliate: <affiliate-id>"
```

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/v3/swap/quote">
    Full Socket Swap V3 API reference
  </Card>

  <Card title="Get API Access" icon="key" href="/integrate/get-api-access">
    Request production API credentials
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.