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