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

# Guide to Integrate Socket API

The Socket Swap V3 API routes same-chain swaps, cross-chain swaps, deposit addresses and non-EVM transfers through a single quote-and-execute flow.

This guide covers the end-to-end integration and how to submit the returned transaction on each chain family.

For full request parameters and response schemas, use the **[API Reference](/v3/swap/quote)** tab.

## Setup

Use the production base URL with your credentials:

```txt theme={null}
https://dedicated-backend.socket.tech
```

Send `x-api-key` and `affiliate` headers. For testing without credentials, use `https://public-backend.socket.tech`. See [Get API Access](/integrate/get-api-access) for the full breakdown.

## Choose your flow

The `userOps` query parameter on `/v3/swap/quote` selects the route type:

| `userOps` | Use when | Origin execution |
| - | - | - |
| `tx` | Your app can sign and submit the origin transaction (connected wallet). | You submit the returned `txData`. |
| `deposit` | The user sends funds themselves (wallet, exchange, non-EVM chain). | User transfers to a deposit address. See [Deposit Addresses](/integrate/integration-guides/deposit-addresses). |
| `cex-withdraw` | Funding originates from a centralized exchange withdrawal. | Requires `exchange` (e.g. `coinbase`). |

This guide covers `userOps=tx`. For the deposit flow (including the `activationRequired` step), see the [Deposit Addresses guide](/integrate/integration-guides/deposit-addresses).

## Core flow

<Steps>
  <Step title="Get a quote">
    Request routes from `/v3/swap/quote` with `userOps=tx`. Same-chain when `originChainId === destinationChainId`, cross-chain otherwise.

    ```bash theme={null}
    curl -sS -G "https://dedicated-backend.socket.tech/v3/swap/quote" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "affiliate: YOUR_AFFILIATE_ID" \
      --data-urlencode "userOps=tx" \
      --data-urlencode "originChainId=8453" \
      --data-urlencode "destinationChainId=42161" \
      --data-urlencode "inputToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
      --data-urlencode "outputToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831" \
      --data-urlencode "inputAmount=1000000" \
      --data-urlencode "userAddress=0xUSER" \
      --data-urlencode "receiverAddress=0xUSER" \
      --data-urlencode "slippage=0.5"
    ```

    Each route carries a `quoteId`, an `expiresAt`, an optional `approval`, the `txData` to submit, and a `statusCheck` block. `userAddress` is required for `tx` routes. See the [quote endpoint](/v3/swap/quote) for the complete field list.
  </Step>

  <Step title="Select a route">
    Rank routes with `routeTags` (`SUGGESTED`, `FASTEST`, `MAX_OUTPUT`,
    `MIN_INPUT`) or compare `output.valueInUsd`, `estimatedTime`, and `gasFee`.
    Discard quotes past `expiresAt`.
  </Step>

  <Step title="Approve (ERC20 only)">
    When the route includes an `approval` object, the ERC20 input must be approved
    to `approval.spenderAddress` (usually Socket's AllowanceHolder, not the final
    bridge or DEX) for at least `approval.amount`.

    The quote does not read your on-chain allowance, so `approval` is present
    whenever a route *could* need it. Check the current allowance yourself and only
    send an approval transaction when it is below `approval.amount`. Native-token
    inputs return no `approval`.
  </Step>

  <Step title="Submit the transaction">
    Submit the route's `txData` from `userAddress`. The `txData.kind` field tells you how — see [Submitting by chain](#submitting-by-chain) below.

    <Warning>
      Do not rebuild calldata client-side. Always submit the returned `txData.object` exactly as provided.
    </Warning>
  </Step>

  <Step title="Poll status">
    Poll `GET /v3/swap/status?quoteId={quoteId}` (cadence suggested in `statusCheck`) until a terminal status: `COMPLETED`, `FAILED`, `EXPIRED`, or `REFUNDED`. `PENDING` and `IN_PROGRESS` are non-terminal.
  </Step>
</Steps>

## Submitting by chain

The quote response returns execution data as `txData.kind` (a discriminator) plus `txData.object`. Submit according to the `kind`:

| `txData.kind` | Chain family | How to submit |
| - | - | - |
| `evm_tx` | EVM | Send `{ to, data, value }` from `userAddress`. |
| `svm_instructions` | Solana | Compile a v0 message from `object.data.instructions` + `lookupTables`, sign, and broadcast. |
| `svm_versioned_tx` | Solana | Deserialize `object.data` (a serialized `VersionedTransaction`), sign, and broadcast. |
| `sui` | Sui | Rebuild from `object.data.transactionBytes` (transaction-kind bytes), set gas + sender, sign, and execute. |
| `tron_tx` | Tron | Trigger the contract with `{ to, data, value }`, sign, and broadcast. |
| `btc_deposit` | Bitcoin | Send `object.amount` (satoshis) to `object.depositAddress` as a native BTC transaction. |

### EVM

```javascript theme={null}
const tx = await signer.sendTransaction({
  to: route.txData.object.to,
  data: route.txData.object.data,
  value: BigInt(route.txData.object.value),
});
```

### Solana

`kind: "svm_instructions"` returns `{ instructions, lookupTables, signers }`. Resolve the lookup tables, compile a v0 `TransactionMessage`, sign with the user's wallet, and send with `connection.sendRawTransaction`.

`kind: "svm_versioned_tx"` returns a serialized `VersionedTransaction` string in `object.data` — deserialize, add the user signature, and broadcast.

<Note>
  For gasless same-chain Solana swaps, pass `solanaSponsorAddress` on the quote.
  The sponsor covers transaction fees and ATA rent. Solana origin only.
</Note>

### Tron

`kind: "tron_tx"` returns EVM-style `{ to, data, value }` where `to` is the contract (often a hex-encoded Tron address). Build the call with `tronWeb.transactionBuilder.triggerSmartContract`, sign, and broadcast. Supported tokens/routes are provider-specific (for example USDT and USDT0 mesh routes).

### Sui

`kind: "sui"` returns `object.data` with `transactionBytes` (transaction-kind bytes only) plus `quoteId`, `coinType`, `packageId`, and `vaultObjectId`. Rebuild with `Transaction.fromKind(transactionBytes)`, set the sender, gas owner, budget, and payment coin, then `build`, sign, and execute. Sui-origin routes settle through the RFQ vault (stablecoin `USDSUI`).

### Bitcoin

`kind: "btc_deposit"` returns `{ depositAddress, amount, orderHash? }`. Construct and broadcast a native Bitcoin transaction sending `amount` satoshis to `depositAddress`; include `orderHash` as an `OP_RETURN` output when present. Bitcoin is a deposit-style origin — there is no signed contract call. Set `refundAddress` to a BTC address for BTC-origin routes.

## Advanced flags

<AccordionGroup>
  <Accordion title="Output / reverse quoting">
    Use `quoteType=EXPECTED_OUTPUT` or `EXACT_OUTPUT` with `outputAmount` to
    target a destination amount instead of fixing the input. The response echoes
    `quoteType`, and matching routes may carry the `MIN_INPUT` tag. Default flow
    is `EXACT_INPUT` + `inputAmount`.
  </Accordion>

  <Accordion title="Simulated quotes">
    Set `simulatedQuotesRequired=true` for same-chain DEX quotes to simulate
    routes on-chain before returning them — reverting quotes are dropped and
    amounts reflect simulation. Simulated routes expose `output.isSimulated` and
    may set `output.quotedAmount` (pre-adjustment amount). Pair with
    `includeQuoteRejections=true` to see filtered providers. Not available with
    output quote types.
  </Accordion>

  <Accordion title="Incognito mode">
    Set `incognito=true` with `userOps=tx` to quote only privacy-capable
    providers (`houdini`, `changenow`). `refundAddress` is required. EVM and
    Solana only; not compatible with output quote types. Same-chain same-token
    is allowed for wallet-to-wallet transfers. See [Incognito
    Mode](/about/features/incognito).
  </Accordion>

  <Accordion title="contractCaller">
    By default the AllowanceHolder requires the signing wallet to also be the
    caller of `AllowanceHolder.exec`. If you route through an intermediate
    contract, the call reverts with `CallerNotSignedUser`. Set `contractCaller`
    to that contract's address to authorize it. Only applies to `userOps=tx`.
  </Accordion>

  <Accordion title="Destination payload">
    Attach `destinationPayload` (with `destinationGasLimit`) to execute calldata
    on the destination chain after bridging. Track execution via
    `isDestPayloadExecuted` on the status response. See [Destination
    Payload](/integrate/integration-guides/additional-guides/destination-payload).
  </Accordion>

  <Accordion title="Integrator fees">
    Set `feeBps` and `feeTakerAddress` together to charge a fee. `feeBps` must
    be between `0` and `10000`. The client-facing output amount is already net
    of fees. For direct bridge no-swap routes, fees are taken on the input side.
  </Accordion>
</AccordionGroup>

## Provider filtering

Restrict routes with `includeProvider` / `excludeProvider` (comma-separated public IDs; they cannot overlap). For the live catalog and full ID list, call `GET /v3/swap/providers` — see [Supported Providers](/about/supported-providers).

<CardGroup cols={2}>
  <Card title="Deposit Addresses" icon="wallet" href="/integrate/integration-guides/deposit-addresses">
    Accept deposits from any chain
  </Card>

  <Card title="Destination Payload" icon="code" href="/integrate/integration-guides/additional-guides/destination-payload">
    Execute calldata on the destination chain
  </Card>

  <Card title="Chain Support" icon="link" href="/about/chain-support">
    See all supported networks
  </Card>

  <Card title="API Reference" icon="book" href="/v3/swap/quote">
    Full request and response schemas
  </Card>
</CardGroup>


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