---
name: Bungee
description: Use when building cross-chain token swap integrations, implementing bridging functionality, creating multi-chain DApps, or helping users move assets between blockchains. Reach for this skill when you need to integrate swap APIs, handle token approvals, monitor transaction status, or choose between automated vs manual routing strategies.
metadata:
    mintlify-proj: bungee
    version: "1.0"
---

# Bungee Skill

## Product summary

Bungee is a cross-chain token swap protocol that enables seamless transfers of any token across 30+ blockchains. It aggregates liquidity from bridges and DEXs to find optimal routes automatically. Agents use Bungee to integrate swap functionality into applications via three methods: **Bungee Link** (redirect to Bungee UI), **Bungee Widget** (embedded component), or **Bungee API** (full programmatic control). The API supports two routing modes: **Auto** (Bungee handles route selection) and **Manual** (integrator selects routes). Key files and endpoints: API base URLs vary by integration type (public sandbox, dedicated backend, frontend), quote endpoint at `/api/v1/bungee/quote`, submit endpoint at `/api/v1/bungee/submit`, status endpoint at `/api/v1/bungee/status`. Primary docs: https://docs.bungee.exchange

## When to use

Reach for this skill when:
- Building a swap or bridge feature into a DApp, wallet, or exchange
- Integrating cross-chain token transfers with minimal setup (use Bungee Link)
- Embedding a swap widget without custom UI (use Bungee Widget)
- Implementing full control over swap routing and execution (use Bungee API)
- Handling ERC20 token approvals with gasless signatures (Permit2 flow)
- Monitoring cross-chain transaction status and completion
- Choosing between automated routing (Bungee Auto) vs manual route selection (Bungee Manual)
- Supporting non-EVM chains like Solana or Tron
- Implementing fee charging on top of Bungee swaps

## Quick reference

### API Integration Types

| Type | Endpoint | Auth | Rate Limit | Use Case |
|------|----------|------|-----------|----------|
| Public Sandbox | `https://public-backend.bungee.exchange/` | None | Very Limited | Testing only |
| Dedicated Backend | `https://dedicated-backend.bungee.exchange/` | API key (`x-api-key`) | 20 RPS | Server-to-server |
| Frontend / Direct | `https://backend.bungee.exchange/` | Domain/IP whitelist | 100 RPM | Frontend/dApp |

### Core API Endpoints

- **Quote**: `GET /api/v1/bungee/quote` — Get pricing and route options
- **Build Transaction**: `GET /api/v1/bungee/build-tx?quoteId={id}` — Build transaction data for Manual routes
- **Submit Request**: `POST /api/v1/bungee/submit` — Submit signed Auto request
- **Status**: `GET /api/v1/bungee/status?requestHash={hash}` — Check transaction status
- **Token List**: `GET /api/v1/tokens/list` — Fetch available tokens per chain
- **Supported Chains**: `GET /api/v1/supported-chains` — List all supported chains

### Status Codes

| Code | Name | Meaning |
|------|------|---------|
| 0 | PENDING | Request submitted, awaiting solver assignment |
| 1 | ASSIGNED | Solver assigned, preparing execution |
| 2 | EXTRACTED | Funds extracted from source chain |
| 3 | FULFILLED | Successfully executed on destination chain |
| 4 | SETTLED | Fully settled and confirmed |
| 5 | EXPIRED | Request timed out, not processed |
| 6 | CANCELLED | Request cancelled by user or system |
| 7 | REFUNDED | Refund processed to user address |

Terminal success states: 3, 4. Terminal failure states: 5, 6, 7.

### Token Address Conventions

- **Native tokens** (ETH, POL, SOL): `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`
- **Wrapped SOL** on Solana: `So11111111111111111111111111111111111111112`
- Always fetch token decimals via `/api/v1/tokens/list` before calculating amounts in wei

### Bungee Link URL Parameters

```
https://bungee.exchange/?originChainId=1&inputToken=0x...&destinationChainId=10&outputToken=0x...
```

| Parameter | Example |
|-----------|---------|
| `originChainId` | 1 (Ethereum), 10 (Optimism), 42161 (Arbitrum) |
| `inputToken` | Token address or `0xeeee...` for native |
| `destinationChainId` | Target chain ID |
| `outputToken` | Destination token address |

## Decision guidance

### When to use Auto vs Manual routing

| Scenario | Use Auto | Use Manual |
|----------|----------|-----------|
| User wants simplest experience | ✅ | ❌ |
| Need gasless approvals (ERC20) | ✅ | ❌ |
| Want to compare multiple routes | ❌ | ✅ |
| Need granular control over execution | ❌ | ✅ |
| Support any token with liquidity | ✅ | ❌ |
| Limited to bridge-supported tokens | ❌ | ✅ |
| Slippage applies to full route | ✅ | ❌ |
| Slippage applies to origin swap only | ❌ | ✅ |

### When to use each integration method

| Method | Effort | Control | Use When |
|--------|--------|---------|----------|
| Bungee Link | Minimal (URL redirect) | None | Simple integration, offload UI to Bungee |
| Bungee Widget | Low (embed component) | Limited | Want swap UI without building custom interface |
| Bungee API | High (full implementation) | Full | Need complete control over UX and routing |

### When to use Permit2 vs traditional approvals

| Aspect | Permit2 (Auto) | Traditional (Manual) |
|--------|---|---|
| Gas cost | One approval + gasless signatures | Two transactions per swap |
| User experience | Better (no approval per swap) | Worse (approval each time) |
| Security | Fine-grained with expiration | Unlimited until revoked |
| Recommended for | ERC20 tokens in Auto mode | Manual mode or native tokens |

## Workflow

### Integrate Bungee Auto with Permit2 (ERC20 tokens)

1. **Get API access**: Request production API key at https://forms.gle/z3q5RdXjouuXR85k9 for dedicated backend or frontend integration
2. **Fetch quote**: Call `/api/v1/bungee/quote` with user address, chain IDs, token addresses, and amount
3. **Check approval**: Read current allowance for Permit2 contract; if insufficient, send ERC20 `approve()` transaction
4. **Sign request**: Extract `signTypedData` from quote response and have user sign the Permit2 message
5. **Submit request**: POST to `/api/v1/bungee/submit` with signed data and `quoteId`
6. **Poll status**: Call `/api/v1/bungee/status` with returned `requestHash` every 5 seconds until terminal state (3, 4, 5, 6, or 7)
7. **Handle completion**: Check if status is 3 or 4 (success) or 5, 6, 7 (failure); extract destination tx hash from response

### Integrate Bungee Manual (granular route control)

1. **Get API access**: Request production credentials
2. **Fetch quote with `enableManual: true`**: Call `/api/v1/bungee/quote` with `enableManual: true` parameter to receive manual routes
3. **Select route**: Choose one route from `manualRoutes` array based on your criteria (price, bridge, etc.)
4. **Build transaction**: Call `/api/v1/bungee/build-tx?quoteId={selectedQuoteId}` to get transaction data
5. **Check approval**: If `approvalData` present, verify allowance and send ERC20 `approve()` if needed
6. **Send transaction**: Execute the transaction data on the origin chain using wallet client
7. **Poll status**: Call `/api/v1/bungee/status?txHash={transactionHash}` every 5 seconds until terminal state
8. **Handle completion**: Check final status code and extract destination tx hash if successful

### Quick Bungee Link integration

1. Build URL with chain IDs and token addresses: `https://bungee.exchange/?originChainId=1&inputToken=0xeeee...&destinationChainId=10&outputToken=0x...`
2. Render as link or redirect users to this URL
3. Users complete swap in Bungee UI and return to your app

## Common gotchas

- **Quote expiry**: Quotes are valid for ~60 seconds. If token approval takes time, refresh the quote before signing to avoid stale `quoteId`
- **`approvalData` is not a transaction**: The API returns raw parameters, not a pre-built transaction. Construct the `approve()` call yourself using the token address, spender, and amount
- **Always check onchain allowance**: Even if API returns `approvalData`, verify current allowance before prompting user—they may already have sufficient approval
- **Native token address**: Use `0xeeee...` for native tokens (ETH, POL, etc.), not the zero address
- **Token decimals matter**: Always fetch decimals from `/api/v1/tokens/list` before calculating `inputAmount` in wei; off-by-one errors cause silent failures
- **Slippage behavior differs**: In Auto mode, slippage applies to the full route; in Manual mode, it applies only to the origin swap
- **Manual routes require `enableManual: true`**: Without this parameter, only auto routes are returned
- **Status polling timeout**: Set a reasonable max attempts (e.g., 60 attempts × 5 seconds = 5 minutes) to avoid infinite loops
- **Server request ID for debugging**: Always capture the `server-req-id` header from responses and include it in error messages for support
- **Smart contract wallets**: If wallet doesn't support EIP-1271, fall back to BungeeInbox contract for Auto requests instead of Permit2
- **Affiliate tracking**: Include `affiliate` header with your affiliate ID to track volume and earnings
- **Rate limits enforced per API key**: Dedicated backend has 20 RPS per key; frontend has 100 RPM per IP; don't exceed or requests will fail

## Verification checklist

Before submitting work with Bungee integration:

- [ ] API key is stored securely (backend only, never in frontend code)
- [ ] Quote response includes required fields (`autoRoute` or `manualRoutes`, `quoteId`)
- [ ] Token approval is checked onchain before prompting user
- [ ] Permit2 signature includes correct `primaryType: "PermitWitnessTransferFrom"`
- [ ] Request submission includes both `userSignature` and `quoteId`
- [ ] Status polling handles all terminal states (3, 4, 5, 6, 7) correctly
- [ ] Error handling captures and logs `server-req-id` header
- [ ] Native token address uses `0xeeee...` convention
- [ ] Token amounts are calculated with correct decimals
- [ ] Affiliate ID is included in request headers if monetizing
- [ ] Quote expiry is handled (refresh if approval takes >30 seconds)
- [ ] Manual routes use `enableManual: true` parameter
- [ ] Slippage behavior matches routing mode (Auto vs Manual)

## Resources

**Comprehensive page navigation**: https://docs.bungee.exchange/llms.txt

**Critical documentation**:
- [Integration Introduction](https://docs.bungee.exchange/integrate/integration-introduction) — Overview of all integration methods and flow
- [Get API Access](https://docs.bungee.exchange/integrate/get-api-access) — API endpoint details, authentication, rate limits
- [Auto Routing with Permit2](https://docs.bungee.exchange/integrate/integration-guides/auto-erc20-permit2) — Complete ERC20 integration example with gasless approvals
- [Manual Routing](https://docs.bungee.exchange/integrate/integration-guides/manual) — Granular route selection and execution
- [Request Status Codes](https://docs.bungee.exchange/integrate/integration-guides/check-status) — Status monitoring and polling patterns
- [Routing Methods Comparison](https://docs.bungee.exchange/overview/routing-methods/routing-methods) — Auto vs Manual feature comparison
- [Chain Support](https://docs.bungee.exchange/overview/chain-support) — Which chains support Auto vs Manual

---

> For additional documentation and navigation, see: https://docs.bungee.exchange/llms.txt