---
name: Bungee
description: Use when building cross-chain swap and bridge integrations, implementing deposit address flows, quoting routes across 50+ chains, executing transactions, monitoring swap status, or charging integrator fees. Essential for agents that need to move assets across blockchains, quote routes, or track transaction completion.
metadata:
    mintlify-proj: bungee
    version: "1.0"
---

# Socket Skill

## Product Summary

Socket is a universal routing engine for moving assets across 50+ blockchains and payment methods. Agents use Socket to quote swap and bridge routes, execute transactions, create deposit addresses, and monitor completion through a single API. The core workflow is: request a quote from `/v3/swap/quote`, select a route, submit the transaction, and poll `/v3/swap/status` for completion.

**Key files and endpoints:**
- Production API: `https://dedicated-backend.socket.tech` (requires API key)
- Testing API: `https://public-backend.socket.tech` (no auth)
- Core endpoints: `/v3/swap/quote`, `/v3/swap/status`, `/v3/swap/supported-chains`, `/v3/swap/tokens/list`
- Contract addresses: AllowanceHolder and OpenRouter deployed on 30+ chains (see `/integrate/contract-addresses`)
- Widget package: `@socket.tech/widget` (React component for UI)

**Primary docs:** https://docs.socket.tech/integrate/introduction

## When to Use

Reach for Socket when:
- **Quoting routes**: User needs to move assets across chains or swap same-chain; request a quote to compare bridge providers, DEX liquidity, and execution times
- **Executing swaps**: User has approved a route and needs to submit the transaction and monitor completion
- **Deposit flows**: User needs to send funds from a wallet, exchange, or non-EVM chain without signing in the same flow (use deposit addresses)
- **Charging fees**: Your app needs to collect integrator fees on swaps (set `feeBps` and `feeTakerAddress`)
- **Multi-chain support**: App needs to support EVM, Solana, Tron, or Stellar in one integration
- **Status tracking**: Monitor pending transactions and detect completion or failure

Do not use Socket for: wallet connection, token approval UI, or authentication — those are your app's responsibility.

## Quick Reference

### API Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/v3/swap/quote` | GET | Fetch executable routes with pricing, gas, and execution details |
| `/v3/swap/status` | GET | Poll transaction status by `quoteId` |
| `/v3/swap/supported-chains` | GET | List supported chain IDs |
| `/v3/swap/tokens/list` | GET | Get curated or complete token list |
| `/v3/swap/tokens/search` | GET | Search tokens by address, name, or symbol |

### Required Query Parameters for `/v3/swap/quote`

| Parameter | Type | Notes |
|-----------|------|-------|
| `userOps` | string | `tx` for direct routes, `deposit` for deposit addresses, `cex-withdraw` for CEX withdrawals |
| `originChainId` | string | Source chain ID (required for `tx` and `deposit`) |
| `destinationChainId` | string | Destination chain ID |
| `inputToken` | string | Source token address (native: `0xEeeeeEeeeEeEeeEeEeEeeEEeeeeEeeeeeeeEEeE`) |
| `inputAmount` | string | Amount in smallest units (wei for EVM) |
| `outputToken` | string | Destination token address |
| `receiverAddress` | string | Destination wallet address |
| `userAddress` | string | Source wallet signing the transaction (required for `tx`) |

### Optional Query Parameters

| Parameter | Type | Use Case |
|-----------|------|----------|
| `slippage` | number | Slippage tolerance (e.g., `0.5` for 0.5%) |
| `feeBps` | number | Integrator fee in basis points (requires `feeTakerAddress`) |
| `feeTakerAddress` | string | Address receiving fees (requires `feeBps`) |
| `includeProvider` | string | Comma-separated provider IDs to include |
| `excludeProvider` | string | Comma-separated provider IDs to exclude |
| `refuel` | boolean | Request gas refuel on destination chain |
| `contractCaller` | string | Intermediate contract address if routing through your contract |
| `refundAddress` | string | Refund address for deposit/CEX flows |

### Authentication

| Endpoint | Auth Method | Rate Limit | Use Case |
|----------|-------------|-----------|----------|
| `public-backend.socket.tech` | None | Shared | Testing, prototyping |
| `backend.socket.tech` | Domain whitelist + `affiliate` header | Standard | Frontend/widget |
| `dedicated-backend.socket.tech` | `x-api-key` + `affiliate` header | 20 rps (100 rps enterprise) | Production backend |

### Response Fields (Quote)

| Field | Type | Description |
|-------|------|-------------|
| `quoteId` | string | Stable route ID for status polling |
| `expiresAt` | number | Unix timestamp; discard if expired |
| `output.amount` | string | Expected destination amount (net of fees) |
| `output.minAmountOut` | string | Minimum acceptable output |
| `routeTags` | array | `SUGGESTED`, `FASTEST`, `MAX_OUTPUT` |
| `approval` | object | Present if ERC20 approval needed; approve `spenderAddress` first |
| `txData.object` | object | Transaction to submit from `userAddress` |
| `gasFee.estimatedFee` | string | Estimated gas cost in native token |
| `statusCheck.endpoint` | string | Suggested polling endpoint |

### Status Codes

| Status | Meaning |
|--------|---------|
| `PENDING` | Quote or route not started |
| `IN_PROGRESS` | Source transaction confirmed, destination pending |
| `COMPLETED` | Route finished successfully |
| `FAILED` | Route execution failed |
| `EXPIRED` | Quote or execution window expired |
| `REFUNDED` | Funds refunded to user |

## Decision Guidance

### When to Use API vs Widget

| Scenario | Use API | Use Widget |
|----------|---------|-----------|
| Full control over routing, UX, and flow | ✓ | — |
| Need to embed swap UI in existing app | — | ✓ |
| Building a backend service | ✓ | — |
| Want drop-in React component | — | ✓ |
| Require custom fee logic | ✓ | — |
| Need multi-chain support (EVM, Solana, Tron) | ✓ | ✓ |

### When to Use Deposit Addresses vs Direct Swaps

| Scenario | Use Deposit | Use Direct Swap |
|----------|-------------|-----------------|
| User sending from exchange or non-EVM chain | ✓ | — |
| User has no wallet connected | ✓ | — |
| User wants to sign once and transfer | ✓ | — |
| User has wallet ready to sign | — | ✓ |
| Need immediate execution | — | ✓ |
| Supported on EVM, Solana, Tron, Stellar | ✓ | ✓ |

### When to Use Provider Filters

| Scenario | Action |
|----------|--------|
| Want fastest route | Use `routeTags: FASTEST` |
| Want maximum output | Use `routeTags: MAX_OUTPUT` |
| Exclude unreliable bridge | Set `excludeProvider: bridge-id` |
| Only use specific DEX | Set `includeProvider: dex-id` |
| No preference | Omit filters; use `SUGGESTED` |

## Workflow

### Standard Swap/Bridge Flow

1. **Request a quote**: Call `/v3/swap/quote` with source chain, destination chain, token pair, amount, and user address.
   - Check `expiresAt` — discard if expired.
   - Review `routeTags` and `output.amount` to select best route.

2. **Check approval**: If `approval` field is present, approve `approval.spenderAddress` for `approval.amount` of `approval.tokenAddress` before proceeding.
   - Approval is usually to AllowanceHolder, not the final bridge/DEX.

3. **Submit transaction**: Send `txData.object` as a transaction from `userAddress`.
   - Do not rebuild calldata; use `txData` exactly as returned.
   - For EVM: use `sendTransaction` with `to`, `data`, `value`.
   - For Solana: deserialize and sign the transaction.
   - For Tron: use TronWeb to sign and broadcast.

4. **Poll status**: Call `/v3/swap/status?quoteId=<quoteId>` every 5–10 seconds.
   - Poll until status reaches terminal state (`COMPLETED`, `FAILED`, `EXPIRED`, `REFUNDED`).
   - Capture `server-req-id` header for debugging.

### Deposit Address Flow

1. **Request quote with deposit mode**: Call `/v3/swap/quote` with `enableDepositAddress=true` and `refundAddress=USER_ADDRESS`.
   - Response includes `deposit.requestHash` and `deposit.txData`.

2. **Display or submit deposit**: Use `deposit.depositData` to show transfer details (recipient, token, amount, memo) or submit `deposit.txData` programmatically.
   - For Stellar: ensure receiver has USDC trustline before first transfer.

3. **Poll status**: Call `/v3/swap/status?requestHash=<requestHash>` until terminal state.

### Fee Implementation

1. **Add fee parameters to quote**: Include `feeBps` (basis points) and `feeTakerAddress` (fee recipient address).
   - Example: `feeBps=50` charges 0.5%.
   - Both parameters required together.

2. **Submit transaction**: Proceed normally; fees are deducted from input or output depending on route type.
   - Client-facing output amount is already net of fees.

## Common Gotchas

- **Expired quotes**: Always check `expiresAt` before submitting. Expired quotes will fail.
- **Missing approval**: If `approval` is present, you must approve before submitting `txData`. Skipping this causes transaction revert.
- **Rebuilding calldata**: Never rebuild `txData` client-side. Use the returned object exactly as provided.
- **Wrong `contractCaller`**: If your integration routes through an intermediate contract, set `contractCaller` to that contract's address. Omitting it causes `CallerNotSignedUser` revert.
- **Native token address**: Use `0xEeeeeEeeeEeEeeEeEeEeeEEeeeeEeeeeeeeEEeE` for native tokens (ETH, MATIC, etc.), not `0x0`.
- **Identical input/output tokens**: Same-chain quotes reject identical `inputToken` and `outputToken`.
- **Solana transaction format**: Deserialize as VersionedTransaction first; fall back to legacy if that fails.
- **Stellar trustlines**: Receiver must have USDC trustline before first deposit to Stellar.
- **Tron constraints**: Tron deposit only supports USDT0 OFT → USDT on Tron; no other tokens or swaps.
- **API key exposure**: Keep `x-api-key` server-side; never expose in frontend code.
- **Slippage too tight**: If slippage is too low, routes may not execute. Use `suggestedSlippage` from response as baseline.
- **Empty route list**: Quote may return empty routes if providers fail, route is unsupported, or filters exclude all providers. Handle gracefully.

## Verification Checklist

Before submitting work:

- [ ] Quote is not expired (`expiresAt` is in the future)
- [ ] Approval is submitted if `approval` field is present
- [ ] Transaction is submitted from correct `userAddress`
- [ ] `txData` is used exactly as returned (no client-side rebuilding)
- [ ] Status polling uses correct `quoteId` or `requestHash`
- [ ] Status polling continues until terminal state (not just first response)
- [ ] `server-req-id` header is captured for debugging
- [ ] For deposit flows: `refundAddress` is set explicitly
- [ ] For fees: both `feeBps` and `feeTakerAddress` are provided together
- [ ] For Stellar: receiver has USDC trustline before transfer
- [ ] For Solana: transaction is deserialized and signed correctly
- [ ] For Tron: using TronWeb instance from wallet provider
- [ ] Error responses include `server-req-id` for support tickets

## Resources

**Comprehensive navigation:** https://docs.socket.tech/llms.txt

**Critical pages:**
- [Socket API Integration Guide](https://docs.socket.tech/integrate/integration-guides/socket-api) — Full request/response reference, status codes, provider IDs
- [Get API Access](https://docs.socket.tech/integrate/get-api-access) — Endpoint selection, authentication, rate limits
- [Deposit Addresses](https://docs.socket.tech/integrate/integration-guides/deposit-addresses) — Non-EVM and deposit flows with code examples

---

> For additional documentation and navigation, see: https://docs.socket.tech/llms.txt