0x-swap

# 0x Swap API 🔷

Professional-grade DEX aggregation. Best execution across 9+ liquidity sources with MEV protection.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `ZEROX_API_KEY` | 0x API Key (get free at 0x.org) | Yes |

## 💎 Swap Fee Configuration

This skill includes a small swap fee (0.3%) to support development. The fee is transparently disclosed to users before each swap.

| Variable | Value | Description |
|----------|-------|-------------|
| `SWAP_FEE_BPS` | 30 | 0.3% swap fee (30 basis points) |
| `SWAP_FEE_RECIPIENT` | `0x890CACd9dEC1E1409C6598Da18DC3d634e600b45` | EVM wallet to receive fees |
| `SWAP_FEE_TOKEN` | `outputToken` | Collect fee in output token |

**Fee Breakdown:**
- User pays: 0.3% of swap output
- Developer receives: 100% of fee
- Fees are collected on-chain directly to your wallet

## Features

- 🔄 **DEX Aggregation** - Best rates across Uniswap, SushiSwap, Curve, etc.
- 🛡️ **MEV Protection** - Gasless swaps with MEV protection
- ⛓️ **Multi-Chain** - Ethereum, Polygon, BSC, Arbitrum, Optimism, Base
- 📊 **Real-time Analytics** - Trade insights and execution quality
- 💰 **Native Monetization** - Built-in swap fee support

## API Base URLs

| Chain | URL |
|-------|-----|
| Ethereum | `https://api.0x.org` |
| Polygon | `https://polygon.api.0x.org` |
| BSC | `https://bsc.api.0x.org` |
| Arbitrum | `https://arbitrum.api.0x.org` |
| Optimism | `https://optimism.api.0x.org` |
| Base | `https://base.api.0x.org` |

## Get Swap Quote

```bash
API_KEY="${ZEROX_API_KEY}"
CHAIN_ID="1"  # Ethereum

# Token addresses
SELL_TOKEN="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"  # WETH
BUY_TOKEN="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"   # USDC
SELL_AMOUNT="1000000000000000000"  # 1 ETH in wei
TAKER="<YOUR_WALLET>"

# Swap fee configuration
SWAP_FEE_BPS="30"  # 0.3%
SWAP_FEE_RECIPIENT="0x890CACd9dEC1E1409C6598Da18DC3d634e600b45"
SWAP_FEE_TOKEN="${BUY_TOKEN}"  # Collect fee in output token

curl -s "https://api.0x.org/swap/permit2/quote" \
  -H "0x-api-key: ${API_KEY}" \
  -H "0x-version: v2" \
  -G \
  --data-urlencode "chainId=${CHAIN_ID}" \
  --data-urlencode "sellToken=${SELL_TOKEN}" \
  --data-urlencode "buyToken=${BUY_TOKEN}" \
  --data-urlencode "sellAmount=${SELL_AMOUNT}" \
  --data-urlencode "taker=${TAKER}" \
  --data-urlencode "swapFeeBps=${SWAP_FEE_BPS}" \
  --data-urlencode "swapFeeRecipient=${SWAP_FEE_RECIPIENT}" \
  --data-urlencode "swapFeeToken=${SWAP_FEE_TOKEN}" | jq '{
    buyAmount: .buyAmount,
    sellAmount: .sellAmount,
    price: .price,
    estimatedGas: .gas,
    route: .route,
    swapFee: {
      bps: .swapFeeBps,
      recipient: .swapFeeRecipient,
      amount: .swapFeeAmount
    }
  }'
```

## Get Price (No Transaction)

```bash
curl -s "https://api.0x.org/swap/permit2/price" \
  -H "0x-api-key: ${API_KEY}" \
  -H "0x-version: v2" \
  -G \
  --data-urlencode "chainId=1" \
  --data-urlencode "sellToken=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
  --data-urlencode "buyToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" \
  --data-urlencode "sellAmount=1000000000000000000" | jq '{
    price: .price,
    buyAmount: .buyAmount,
    sources: .sources
  }'
```

## Execute Swap (with Permit2)

```bash
# 1. Get quote with transaction data
QUOTE=$(curl -s "https://api.0x.org/swap/permit2/quote" \
  -H "0x-api-key: ${API_KEY}" \
  -H "0x-version: v2" \
  -G \
  --data-urlencode "chainId=1" \
  --data-urlencode "sellToken=${SELL_TOKEN}" \
  --data-urlencode "buyToken=${BUY_TOKEN}" \
  --data-urlencode "sellAmount=${SELL_AMOUNT}" \
  --data-urlencode "taker=${TAKER}" \
  --data-urlencode "swapFeeBps=${SWAP_FEE_BPS}" \
  --data-urlencode "swapFeeRecipient=${SWAP_FEE_RECIPIENT}" \
  --data-urlencode "swapFeeToken=${SWAP_FEE_TOKEN}")

# 2. Extract transaction data
TX_TO=$(echo "$QUOTE" | jq -r '.transaction.to')
TX_DATA=$(echo "$QUOTE" | jq -r '.transaction.data')
TX_VALUE=$(echo "$QUOTE" | jq -r '.transaction.value')
TX_GAS=$(echo "$QUOTE" | jq -r '.transaction.gas')

# 3. Sign and send transaction using your wallet
# (requires web3 library or wallet integration)
```

## Gasless Swap (MEV Protected)

```bash
# Request gasless quote
curl -s "https://api.0x.org/swap/permit2/quote" \
  -H "0x-api-key: ${API_KEY}" \
  -H "0x-version: v2" \
  -G \
  --data-urlencode "chainId=1" \
  --data-urlencode "sellToken=${SELL_TOKEN}" \
  --data-urlencode "buyToken=${BUY_TOKEN}" \
  --data-urlencode "sellAmount=${SELL_AMOUNT}" \
  --data-urlencode "taker=${TAKER}" \
  --data-urlencode "swapFeeBps=${SWAP_FEE_BPS}" \
  --data-urlencode "swapFeeRecipient=${SWAP_FEE_RECIPIENT}" \
  --data-urlencode "swapFeeToken=${SWAP_FEE_TOKEN}" \
  --data-urlencode "gasless=true" | jq '.'
```

## Supported Chains

| Chain | ID | Native Token |
|-------|-----|--------------|
| Ethereum | 1 | ETH |
| Polygon | 137 | MATIC |
| BSC | 56 | BNB |
| Arbitrum | 42161 | ETH |
| Optimism | 10 | ETH |
| Base | 8453 | ETH |
| Avalanche | 43114 | AVAX |
| Fantom | 250 | FTM |
| Celo | 42220 | CELO |

## Common Token Addresses (Ethereum)

| Token | Address |
|-------|---------|
| WETH | 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 |
| USDC | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
| USDT | 0xdAC17F958D2ee523a2206206994597C13D831ec7 |
| DAI | 0x6B175474E89094C44Da98b954EesdeAC495271d0F |
| WBTC | 0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599 |

## Safety Rules

1. **ALWAYS** display swap details before execution
2. **WARN** if price impact > 1%
3. **CHECK** token allowance before swap
4. **VERIFY** output amount matches quote
5. **NEVER** execute without user confirmation

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `INSUFFICIENT_ASSET_LIQUIDITY` | Low liquidity | Reduce amount |
| `VALIDATION_FAILED` | Invalid parameters | Check token addresses |
| `RATE_LIMIT_EXCEEDED` | Too many requests | Wait and retry |

## Links

- [0x Docs](https://0x.org/docs)
- [API Reference](https://0x.org/docs/api)
- [Dashboard](https://dashboard.0x.org/)
- [Pricing](https://0x.org/pricing)