---
name: Bungee
description: Use when building cross-chain token swaps, integrating bridging functionality, or implementing multi-chain asset transfers. Agents should reach for this skill when users need to swap tokens across different blockchains, integrate Bungee into applications, or understand routing options for cross-chain transactions.
metadata:
    mintlify-proj: bungee
    version: "1.0"
---

# Bungee Skill

## Product summary

Bungee is a cross-chain token swap protocol that enables seamless swaps between any token on any of 30+ supported blockchains. It processes over $25B in volume and is trusted by major wallets and dApps. Agents use Bungee to integrate cross-chain swaps via API, widget, or link. Key endpoints: `https://public-backend.bungee.exchange/` (sandbox), `https://dedicated-backend.bungee.exchange/` (production with API key), `https://backend.bungee.exchange/` (frontend). Primary integration flow: get quote → create request → submit → monitor status. See [Bungee Integration Guides](https://docs.bungee.exchange/integrate/integration-guides) for detailed implementation.

## When to use

Reach for this skill when:
- Building cross-chain token swap functionality into an application
- Integrating Bungee Auto (automated routing) or Bungee Manual (user-selected routes)
- Implementing bridging for ERC20 tokens, native tokens (ETH, POL), or non-EVM chains (Solana, Tron, HyperCore)
- Handling token approvals, Permit2 signatures, or onchain request submission
- Monitoring swap status and handling completion/failure states
- Choosing between integration methods: API, Widget, Link, or Deposit Addresses
- Troubleshooting quote failures, approval issues, or status tracking

## Quick reference

### API Endpoints & Authentication

| Endpoint | Auth | Rate Limit | Use Case |
|----------|------|-----------|----------|
| `https://public-backend.bungee.exchange/` | None | Very Limited | Testing only |
| `https://dedicated-backend.bungee.exchange/` | API Key (`x-api-key` header) | 20 RPS | Production backend |
| `https://backend.bungee.exchange/` | Domain/IP whitelist | 100 RPM | Frontend/dApp |

### Core API Endpoints

- `GET /api/v1/bungee/quote` — Get swap quote with routing options
- `POST /api/v1/bungee/submit` — Submit signed request (Auto mode)
- `GET /api/v1/bungee/status?requestHash=` or `?txHash=` — Check request status
- `GET /api/v1/bungee/build-tx?quoteId=` — Build transaction for Manual mode
- `GET /api/v1/supported-chains` — List supported chains
- `GET /api/v1/tokens/list` — Get token list (trending or full)
- `GET /api/v1/tokens/search?q=` — Search for specific token

### Status Codes

| Code | Status | Terminal? | Meaning |
|------|--------|-----------|---------|
| 0 | PENDING | No | Request submitted, awaiting solver |
| 1 | ASSIGNED | No | Solver assigned, preparing execution |
| 2 | EXTRACTED | No | Funds extracted from source chain |
| 3 | FULFILLED | Yes | Successfully executed on destination |
| 4 | SETTLED | Yes | Fully settled and confirmed |
| 5 | EXPIRED | Yes | Request timed out |
| 6 | CANCELLED | Yes | Request cancelled |
| 7 | REFUNDED | Yes | Funds refunded to user |

### Native Token Address

For native assets (ETH, POL, etc.), use: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`

### Quote Parameters (Essential)

```
userAddress          - User's wallet address
receiverAddress      - Destination wallet address
originChainId        - Source chain ID (e.g., 1 for Ethereum)
destinationChainId   - Destination chain ID
inputToken           - Source token address
outputToken          - Destination token address
inputAmount          - Amount in wei (with decimals)
enableManual: true   - Required to get Manual routes
useInbox: true       - For ERC20 onchain requests (bypasses Permit2)
```

## Decision guidance

### When to use Auto vs Manual Mode

| Scenario | Use Auto | Use Manual |
|----------|----------|-----------|
| User wants best price automatically | ✅ | ❌ |
| Need gasless approval (Permit2) | ✅ | ❌ |
| User wants to see multiple routes | ❌ | ✅ |
| Any token to any token | ✅ | Limited to bridge-supported tokens |
| Smart contract integration | ✅ | Limited |
| New/emerging chains | ✅ | ❌ |
| Proven, battle-tested solution | ❌ | ✅ |

### When to use each integration method

| Method | Best For | Effort |
|--------|----------|--------|
| **Bungee Link** | Simple redirects with pre-selected chains/tokens | Minimal (URL params) |
| **Bungee Widget** | React apps wanting full UI without custom code | Low (npm package) |
| **Bungee API** | Full control, custom UI, backend integration | High (multi-step flow) |
| **Deposit Addresses** | Non-EVM chains (Solana, Tron, HyperCore) | Medium (chain-specific) |

### When to use each token type

| Token Type | Endpoint | Approval | Signature | Use Case |
|-----------|----------|----------|-----------|----------|
| **Native (ETH, POL)** | `/quote` | None | None | Direct onchain via Inbox |
| **ERC20 + Permit2** | `/quote` | Gasless | Permit2 signature | Recommended for ERC20 |
| **ERC20 + Inbox** | `/quote` with `useInbox: true` | Standard approve | None | Fallback for smart wallets |
| **ERC20 + Manual** | `/quote` with `enableManual: true` | Standard approve | None | Manual route selection |

## Workflow

### Typical Bungee Auto Integration (ERC20 with Permit2)

1. **Get quote**: Call `/api/v1/bungee/quote` with user parameters. Check response for `autoRoute.signTypedData` and `autoRoute.approvalData`.

2. **Handle approval** (if needed): If `approvalData` exists, check current allowance. If insufficient, send approval transaction to Permit2 contract. Wait for confirmation.

3. **Sign request**: Extract `signTypedData` from quote. Use wallet to sign with `primaryType: "PermitWitnessTransferFrom"`. Extract `witness` object from `signTypedData.values`.

4. **Submit signed request**: POST to `/api/v1/bungee/submit` with `requestType`, `request` (witness), `userSignature`, and `quoteId`. Receive `requestHash`.

5. **Poll status**: Call `/api/v1/bungee/status?requestHash=` every 5 seconds. Check `bungeeStatusCode`: terminal states are 3, 4 (success) or 5, 6, 7 (failure).

6. **Handle completion**: On success (code 3 or 4), extract destination tx hash from `status.destinationData.txHash`. On failure, inform user and optionally retry.

### Typical Bungee Manual Integration

1. **Get quote with Manual routes**: Call `/api/v1/bungee/quote` with `enableManual: true`. Response includes `manualRoutes` array.

2. **Select route**: User chooses from multiple routes. Extract `quoteId` from selected route.

3. **Build transaction**: Call `/api/v1/bungee/build-tx?quoteId=` to get `txData` and `approvalData`.

4. **Handle approval**: Check `approvalData`. If present, send approval transaction and wait for confirmation.

5. **Execute transaction**: Send transaction with `txData.to`, `txData.data`, and `txData.value` to blockchain.

6. **Monitor status**: Poll `/api/v1/bungee/status?txHash=` with transaction hash until terminal state.

### Typical Bungee Auto Integration (Native Token)

1. **Get quote**: Call `/api/v1/bungee/quote` with native token address. Response includes `autoRoute.txData` and `autoRoute.requestHash`.

2. **Submit transaction**: Send transaction directly to blockchain using `txData.to`, `txData.data`, and `txData.value` (in wei).

3. **Poll status**: Use `requestHash` to poll `/api/v1/bungee/status?requestHash=` until completion.

## Common gotchas

- **Quote expiry**: Quotes are valid for ~60 seconds. If approval takes time, refresh quote before signing to avoid expired `quoteId`.

- **Token decimals**: Always fetch decimals via `/api/v1/tokens/list`. Calculate `inputAmount` in wei: `humanAmount × 10^decimals`. For HyperCore, use 6-decimal micro-units.

- **Permit2 approval**: `approvalData` is NOT a pre-built transaction. Extract `tokenAddress`, `spenderAddress`, `amount`, and construct approve call yourself. Always check current allowance before prompting user.

- **Native token address**: Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for ETH, POL, etc. This is NOT a real contract.

- **API key security**: Never expose API key in frontend code. Route calls through backend. If frontend must call API, whitelist domain/IP.

- **Server request ID**: Capture `server-req-id` header from all responses. Include in error messages and support tickets for debugging.

- **Status polling timeout**: Set max attempts (e.g., 60 × 5 seconds = 5 minutes). Don't poll indefinitely.

- **Manual mode slippage**: Slippage applies only to origin swap, not bridge. Bridge mechanics differ from swaps.

- **Smart wallet fallback**: If wallet doesn't support EIP-1271, use `useInbox: true` or BungeeInbox contract instead of Permit2.

- **Refund recipient**: On source chain refund, funds go to `msg.sender` (onchain) or `userAddress` (API). On destination, funds go to `receiverAddress`.

## Verification checklist

Before submitting work:

- [ ] Quote request includes all required parameters: `userAddress`, `receiverAddress`, `originChainId`, `destinationChainId`, `inputToken`, `outputToken`, `inputAmount`
- [ ] Token addresses are valid (use native token address for ETH/POL)
- [ ] Input amount is in wei with correct decimals
- [ ] For Manual mode, `enableManual: true` is set in quote request
- [ ] For ERC20 onchain, `useInbox: true` is set if needed
- [ ] Approval is checked before prompting user (compare current allowance to required amount)
- [ ] Permit2 signature uses correct `primaryType: "PermitWitnessTransferFrom"`
- [ ] Request submission includes `requestType`, `request` (witness), `userSignature`, `quoteId`
- [ ] Status polling checks for terminal states (3, 4, 5, 6, 7)
- [ ] Error handling captures `server-req-id` for debugging
- [ ] Timeout logic prevents infinite polling
- [ ] Destination tx hash is extracted from `status.destinationData.txHash` on success
- [ ] Chain is supported (check [chain support table](https://docs.bungee.exchange/overview/chain-support))

## Resources

- **Comprehensive navigation**: [Bungee docs llms.txt](https://docs.bungee.exchange/llms.txt) — Full page-by-page reference
- **Integration guides**: [Bungee Integration Guides](https://docs.bungee.exchange/integrate/integration-guides) — Step-by-step for Auto, Manual, Widget, Link
- **API reference**: [Bungee API Reference](https://docs.bungee.exchange/api-reference) — OpenAPI spec with all endpoints
- **Status codes**: [Request Status Codes](https://docs.bungee.exchange/integrate/integration-guides/check-status) — Detailed status explanations and polling examples

---

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