# Tollbooth Examples — AI Agent Token Swaps with x402 Micropayments

Working, copy-paste examples for letting an autonomous AI agent **swap tokens**
and **screen tokens for honeypots/rug pulls** using
[Tollbooth](https://api.tollboothswap.xyz) and the
[x402 payment protocol](https://www.x402.org). No API keys, no accounts, no
custody: the agent pays ~half a cent in USDC per call and signs its own
transactions.

Supported chains: **Solana, Base, Ethereum, Arbitrum, Polygon, Optimism, BSC,
Avalanche** (Jupiter aggregation on Solana, 0x on EVM chains).

## How it works

1. `GET /v1/tokens/:chain/:symbol` — resolve a ticker like `PEPE` to contract
   addresses, ranked by DEX liquidity (**free**)
2. `GET /v1/quote` — fee-inclusive swap quote (**free**)
3. `GET /v1/check/:chain/:token` — honeypot / rug-pull safety check
   (**x402, $0.01**)
4. `POST /v1/swap/build` — unsigned, ready-to-sign swap transaction
   (**x402, ~$0.005**)
5. Your agent signs and submits with its own wallet. Tollbooth never touches
   keys or funds.

Tolls are payable in USDC on **Base** (gasless via EIP-3009) or **Solana
mainnet** (gas sponsored by the facilitator — the payer wallet needs zero
SOL). The `@x402/fetch` client handles the whole 402 payment loop
automatically.

## Run the examples

```bash
npm install --legacy-peer-deps

# free endpoints, no wallet needed
npx tsx examples/01-resolve-and-quote.ts

# paid endpoints: fund a wallet with a little USDC on Base first
PAYER_KEY=0x... npx tsx examples/02-safety-check.ts
PAYER_KEY=0x... TAKER=<your wallet> npx tsx examples/03-build-swap.ts

# pay tolls from a Solana wallet instead (USDC on Solana mainnet, no SOL needed)
SOLANA_PAYER_KEYPAIR=/path/to/keypair.json npx tsx examples/04-solana-payer.ts
```

## Use from MCP (Claude, Cursor, any MCP client)

Tollbooth also ships an MCP server exposing `resolve_token`, `get_quote`,
`check_token`, `build_swap` and `get_receipt` as tools. Example config in
[`mcp.json`](./mcp.json).

## Docs

- Agent usage guide: https://api.tollboothswap.xyz/skill.md
- Full tutorial: https://api.tollboothswap.xyz/guides/agent-swaps.md
- Service manifest: https://api.tollboothswap.xyz/.well-known/x402-service
- x402 Bazaar (service discovery for agents): https://docs.cdp.coinbase.com/x402/bazaar

## Keywords

AI agent token swap, x402 payment protocol example, autonomous agent DeFi,
Solana swap API for agents, honeypot checker API, rug pull detection API,
non-custodial swap transaction builder, USDC micropayments, HTTP 402,
machine-to-machine payments, Jupiter aggregator API, 0x swap API, MCP DeFi
tools.

## License

MIT