BaseAlpha
Agent API

Trade programmatically on Base Alpha

x402-protected API endpoints for AI agents. Get best-price quotes aggregated across Aerodrome, Uniswap V3, and PancakeSwap in a single call. Pay per request with USDC on Base.

How x402 Payment Works

1
Request
Call any agent endpoint without a payment header
2
402 Response
Receive payment requirements (USDC on Base, exact amount)
3
Pay & Access
Sign payment via x402, attach X-PAYMENT header, get data

MCP Server

Connect to Claude Desktop, Cursor, or any MCP client for tool-use access to all endpoints.

claude_desktop_config.json
{
  "mcpServers": {
    "base-alpha": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote@latest",
               "https://base-alpha.xyz/api/mcp"]
    }
  }
}

Uses playground endpoints (no x402 payment) for read-only tools. See llms.txt and openapi.json for full API spec.

Endpoints

GETread-only/api/agent/quote$0.001
Best swap quote across all DEXes
tokenIn, tokenOut, amountIn, slippageBps?
POSTmutation/api/agent/swap$0.01
Build unsigned swap transaction
tokenIn, tokenOut, amountIn, recipient, slippageBps?
GETread-only/api/agent/tokens$0.001
List tokens with USD prices
none
GETread-only/api/agent/pools$0.001
List liquidity pools
token0?, token1?
GETread-only/api/agent/prices$0.001
USD prices for all known tokens
tokens? (comma-separated addresses)
GETread-only/api/agent/ohlcv$0.001
OHLCV candlestick data for a pool
pool, timeframe?, aggregate?
GETread-only/api/agent/trades$0.001
Recent on-chain trades for a pool
pool, token0Decimals?, token1Decimals?, invert?, v2?
GETread-only/api/agent/volume$0.001
24h & all-time volume, active traders, fee revenue
none

Live Playground

Try endpoints directly — live data, no payment required

Request URL
/api/agent/playground?endpoint=quote&tokenIn=0x4200000000000000000000000000000000000006&tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amountIn=1000000000000000000

Select an endpoint and click "Try It" to see live results

Integration Example

curl
# Step 1: Get 402 response with payment requirements
curl -s https://base-alpha.xyz/api/agent/quote\
  ?tokenIn=0x4200000000000000000000000000000000000006\
  &tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\
  &amountIn=1000000000000000000

# Step 2: Pay with x402 header (after signing)
curl -s -H "X-PAYMENT: <base64-payment-header>" \
  https://base-alpha.xyz/api/agent/quote\
  ?tokenIn=0x4200000000000000000000000000000000000006\
  &tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\
  &amountIn=1000000000000000000
TypeScript
import { createPaymentHeader } from "x402/client";
import { createSigner } from "x402/types";

const signer = createSigner(walletClient);
const url = "https://base-alpha.xyz/api/agent/quote"
  + "?tokenIn=0x4200000000000000000000000000000000000006"
  + "&tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  + "&amountIn=1000000000000000000";

// First call returns 402 with payment requirements
const res = await fetch(url);
const { accepts } = await res.json();

// Sign and pay
const header = await createPaymentHeader(signer, 1, accepts[0]);
const paidRes = await fetch(url, {
  headers: { "X-PAYMENT": header }
});
const quote = await paidRes.json();
console.log(quote);
// { amountOut: "3215000000", dexName: "Aerodrome", ... }

Error Handling

400Invalid paramsNot retryable
Fix request parameters
402Payment requiredRetryable
Sign x402 payment header
402Payment failedRetryable
Re-sign with fresh nonce
404No liquidityNot retryable
Try a different token pair
500Internal errorRetryable
Exponential backoff 1s/2s/4s
TypeScript retry helper
async function fetchWithRetry(url: string, opts?: RequestInit, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, opts);
    if (res.ok) return res.json();

    const body = await res.json().catch(() => ({}));
    const retryable = res.status === 402 || res.status >= 500;
    if (!retryable || i === retries - 1) {
      throw new Error(body.error ?? `HTTP ${res.status}`);
    }
    await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
  }
}

Agent Templates

Copy-paste recipes to get started

Poll prices and alert on threshold cross

read-only
/prices
import { fetchWithRetry } from "./retry";

const WETH = "0x4200000000000000000000000000000000000006";
const THRESHOLD_USD = 3000;

async function monitorPrice(intervalMs = 30_000) {
  while (true) {
    const data = await fetchWithRetry(
      `https://base-alpha.xyz/api/agent/prices?tokens=${WETH}`
    );
    const price = parseFloat(data.prices?.[WETH]?.usd ?? "0");
    console.log(`WETH: $${price.toFixed(2)}`);

    if (price >= THRESHOLD_USD) {
      console.log("ALERT: WETH crossed $" + THRESHOLD_USD);
      // send notification...
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
}
monitorPrice();

Common Token Addresses

WETH0x420000000000000000000000000000000000000618 dec
USDC0x833589fCD6eDb6E08f4c7C32D4f71b54bdA029136 dec
cbBTC0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf8 dec
AERO0x940181a94A35A4569E4529A3CDfB74e38FD9863118 dec
On-chain swap fees (currently 0%) are separate from x402 API fees. Swaps route through the FeeRouter contract. See llms.txt for machine-readable API docs.