Token Trading

AgnicPay lets you swap tokens directly on Base through the API. Trades are executed via 0x Protocol DEX aggregation for best pricing across multiple liquidity sources.

How It Works

sequenceDiagram
    participant Client
    participant AgnicPay
    participant 0x Protocol
    participant Base Chain
 
    Client->>AgnicPay: POST /api/trade (USDC → ETH)
    AgnicPay->>0x Protocol: Get best quote
    0x Protocol-->>AgnicPay: Quote + swap calldata
    AgnicPay->>Base Chain: Approve token (if needed)
    AgnicPay->>Base Chain: Execute swap tx
    Base Chain-->>AgnicPay: Tx receipt
    AgnicPay-->>Client: Trade result + tx hash

Supported Tokens

Token	Address	Decimals
USDC	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	6
ETH	Native	18
WETH	`0x4200000000000000000000000000000000000006`	18
cbETH	`0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22`	18
DAI	`0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb`	18
AERO	`0x940181a94A35A4569E4529A3CDfB74e38FD98631`	18

You can also pass raw contract addresses instead of symbols.

Trading is currently available on Base mainnet only. All trades are executed on-chain through 0x Protocol aggregation.

Execute a Trade

POST /api/trade

Request Body

Parameter	Type	Required	Description
`sellToken`	string	Yes	Token to sell (symbol or address)
`buyToken`	string	Yes	Token to buy (symbol or address)
`sellAmount`	number	Yes	Amount to sell (human-readable units)
`slippagePercentage`	number	No	Max slippage % (default: 1.0)
`network`	string	No	Network (default: "base")

Example

curl -X POST https://api.agnic.ai/api/trade \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "USDC",
    "buyToken": "ETH",
    "sellAmount": 10,
    "slippagePercentage": 1.0
  }'

Response

{
  "success": true,
  "transactionHash": "0xabc123...",
  "sellToken": "USDC",
  "sellAmount": 10,
  "buyToken": "ETH",
  "buyAmount": "0.00396",
  "price": "2525.25",
  "slippage": "1%",
  "network": "base",
  "explorerUrl": "https://basescan.org/tx/0xabc123..."
}

Get a Quote (Dry Run)

Preview a trade without executing it.

GET /api/trade/quote

Query Parameters

Parameter	Type	Required	Description
`sellToken`	string	Yes	Token to sell
`buyToken`	string	Yes	Token to buy
`sellAmount`	number	Yes	Amount to sell

Example

curl "https://api.agnic.ai/api/trade/quote?sellToken=USDC&buyToken=ETH&sellAmount=10" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"

Response

{
  "sellToken": "USDC",
  "buyToken": "ETH",
  "sellAmount": 10,
  "buyAmount": "0.00396",
  "price": "2525.25",
  "slippage": "1%",
  "gas": "0.0001",
  "network": "base"
}

List Supported Tokens

GET /api/trade/tokens

No authentication required. Returns all tokens available for trading.

curl https://api.agnic.ai/api/trade/tokens

Spending Limits

Trades are subject to the same spending limits as other transactions:

Per-transaction limit: Based on the sell amount in USD
Daily limit: Rolling 24-hour total
Monthly limit: Rolling 30-day total

Trades use the sell-side USD value for limit calculations.

Using the CLI

# Preview a trade
agnic trade 10 usdc eth --dry-run
 
# Execute a trade
agnic trade 10 usdc eth
 
# With custom slippage
agnic trade 10 usdc eth --slippage 0.5

Using the MCP Server

The trade_tokens MCP tool is available when connected to the AgnicPay MCP server:

{
  "tool": "trade_tokens",
  "parameters": {
    "sellToken": "USDC",
    "buyToken": "ETH",
    "sellAmount": 10
  }
}

Token Trading

Token Trading

How It Works

Supported Tokens

Execute a Trade

Request Body

Example

Response

Get a Quote (Dry Run)

Query Parameters

Example

Response

List Supported Tokens

Spending Limits

Using the CLI

Using the MCP Server

Next Steps

CLI Reference

API Reference

Balance

On this page