Quick Start

Axon API Documentation

Everything you need to integrate DeFi protocols into your AI agent. Discover protocols, build transactions, and execute on-chain — all through a single REST API.

⚡

First API call in 30 seconds

1

Get your API key

Free — 50 requests/day

2

Make first call

List available protocols

3

Build transactions

Generate executable calldata

Step 1 — Generate a free API key

curl -X POST https://axon.nanocorp.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response includes your key as ax-<64-char-hex>. Save it — it's shown only once.

Want higher limits? Get Early Access for 10,000 requests/day.

Step 2 — List available protocols

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/protocols

Step 3 — Build a swap transaction

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenOut": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "fee": "3000",
    "recipient": "0xYourWalletAddress",
    "amountIn": "1000000000",
    "amountOutMinimum": "0"
  }' \
  https://axon.nanocorp.app/api/v1/protocols/uniswap-v3/actions/exact_input_single/build

TIPThat's it. You just discovered a protocol, its actions, and built a real Uniswap swap transaction in 3 API calls.

Authentication

All API requests (except POST /keys and GET /health) require a Bearer token in the Authorization header.

How to get an API key

1

Free tier (50 req/day)

Call POST /api/v1/keys with your email. Instant, no payment needed.

2

Early Access (10,000 req/day)

Purchase Early Access — your key is generated automatically after payment.

Using your key

Include your key as a Bearer token in every request:

terminal

curl -H "Authorization: Bearer ax-a1b2c3d4e5f6..." \
  https://axon.nanocorp.app/api/v1/protocols

Key format

API keys follow the format ax-<64-hex-chars>. Keys are hashed server-side — we never store your raw key. Save it when it's first displayed.

WARNKeep your API key secret. Never expose it in client-side code or public repositories. If compromised, contact us for rotation.

Auth error responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Missing Authorization header. Use: Authorization: Bearer ax-<your-key>"
}

429 Rate Limited

{
  "error": "rate_limit_exceeded",
  "message": "Daily request limit reached. Upgrade to Early Access for 10,000 req/day."
}

Base URL & Rate Limits

All API requests use the following base URL:

bash

https://axon.nanocorp.app/api/v1

The API returns JSON responses with Content-Type: application/json. CORS is enabled for all origins.

Rate Limits

Parameter	Type	Required	Description
`Free tier`	—	optional	50 requests/day — resets at 00:00 UTC
`Early Access`	—	optional	10,000 requests/day — $49 one-time

INFOCheck your current usage anytime with GET /api/v1/usage.

Slug Convention

Every protocol in Axon has two slug formats. All API endpoints accept both formats, so you never need to worry about which style to use.

Chain-specific slug

uniswap-v3-ethereum

Targets a specific chain deployment. Pattern: protocol-chain

Generic slug

uniswap-v3

Auto-resolves to Ethereum mainnet. Great for quick calls.

Resolution Rules

Exact match

If the slug matches a protocol exactly (chain-specific), it's used as-is.

Ethereum default

If no exact match, Axon appends '-ethereum' and tries again. This means generic slugs like 'uniswap-v3' auto-resolve to 'uniswap-v3-ethereum'.

Multi-chain disambiguation

If the protocol exists on multiple chains but not Ethereum, you'll get a 400 error with all available chain-specific slugs.

Not found

If no variant exists at all, you'll get a 404 with a list of all available protocols.

Examples

# Generic slug — auto-resolves to Ethereum mainnet
curl https://axon.nanocorp.app/api/v1/protocols/uniswap-v3 \
  -H "Authorization: Bearer ax-YOUR_KEY"

# Chain-specific slug — targets Base L2
curl https://axon.nanocorp.app/api/v1/protocols/uniswap-v3-base \
  -H "Authorization: Bearer ax-YOUR_KEY"

# Works on ALL endpoints (actions, build, etc.)
curl https://axon.nanocorp.app/api/v1/protocols/aave-v3/actions \
  -H "Authorization: Bearer ax-YOUR_KEY"

INFOWhen a generic slug is resolved, the response includes a _meta object with slug_resolved: true, the original requested_slug, and the resolved_slug. This helps agents understand when auto-resolution occurred.

Best Practices

Use generic slugs for quick Ethereum mainnet interactions
Use chain-specific slugs when targeting L2s (Base, Arbitrum)
The generic_slug field in GET /protocols response shows the generic form of each slug
For transaction building on L2s, always use chain-specific slugs to avoid accidentally targeting Ethereum

API Reference

POST/keys

Generate a free-tier API key. One free key per email address. No authentication required.

Body Parameters

Parameter	Type	Required	Description
`email`	string	required	Your email address. Used for key management and rate limit tracking.

Request

curl -X POST https://axon.nanocorp.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com"}'

Response

201 Created

{
  "api_key": "ax-a1b2c3d4e5f6789...",
  "plan": "free",
  "daily_limit": 50,
  "message": "Save this key — it won't be shown again.",
  "docs": "https://axon.nanocorp.app/docs",
  "upgrade": "Need more? Get 10,000 requests/day with Early Access"
}

WARNSave the api_key immediately. For security, raw keys are never stored and cannot be retrieved later.

GET/usage

Check your API key usage, rate limits, and account details.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/usage

Response

200 OK

{
  "usage": {
    "plan": "free",
    "daily_limit": 50,
    "daily_used": 12,
    "daily_remaining": 38,
    "total_requests": 156,
    "reset_time": "00:00 UTC"
  },
  "account": {
    "email": "agent@example.com",
    "created_at": "2026-03-01T12:00:00Z",
    "last_used_at": "2026-03-07T15:30:00Z"
  }
}

GET/protocols

List all available DeFi protocols with summary metadata including risk scores, TVL, and action counts.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/protocols

Response

200 OK

{
  "protocols": [
    {
      "slug": "uniswap-v3-ethereum",
      "name": "Uniswap",
      "category": "dex",
      "chain": { "id": 1, "name": "ethereum", "network": "mainnet" },
      "description": "Decentralized exchange with concentrated liquidity AMM.",
      "actions_count": 2,
      "risk_score": "A+",
      "tvl_usd": 4800000000
    },
    {
      "slug": "aave-v3-ethereum",
      "name": "Aave",
      "category": "lending",
      "chain": { "id": 1, "name": "ethereum", "network": "mainnet" },
      "description": "Decentralized non-custodial liquidity protocol.",
      "actions_count": 4,
      "risk_score": "A+",
      "tvl_usd": 12500000000
    }
  ]
}

GET/protocols/:slug

Get the full Axon Protocol Spec for a specific protocol, including contracts, actions, risk data, and fee structure.

Path Parameters

Parameter	Type	Required	Description
`slug`	string	required	Protocol identifier. Accepts generic slugs (e.g. uniswap-v3) or chain-specific slugs (e.g. uniswap-v3-ethereum, aave-v3-base). Generic slugs default to Ethereum mainnet.

INFOSlug Resolution: All endpoints accept both generic slugs (e.g. uniswap-v3) and chain-specific slugs (e.g. uniswap-v3-ethereum). Generic slugs automatically resolve to the Ethereum mainnet deployment. For L2 protocols, use chain-specific slugs like uniswap-v3-base or aave-v3-arbitrum. If the protocol has no Ethereum deployment, you will receive a chain_required error listing available chain-specific slugs.

Request

# Generic slug (defaults to Ethereum mainnet)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/protocols/uniswap-v3

# Chain-specific slug (explicit chain)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/protocols/uniswap-v3-base

Response

200 OK

{
  "axon_version": "1.0.0",
  "protocol": {
    "name": "Uniswap",
    "slug": "uniswap-v3-ethereum",
    "version": "v3",
    "category": "dex",
    "chain": { "id": 1, "name": "ethereum", "network": "mainnet" },
    "contracts": {
      "swap_router_02": {
        "address": "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
        "label": "SwapRouter02",
        "verified": true
      }
    },
    "links": {
      "website": "https://uniswap.org",
      "docs": "https://docs.uniswap.org"
    }
  },
  "actions": [ ... ],
  "risk": { ... },
  "fees": { ... }
}

INFOFull spec responses are cached for 1 hour. Use this endpoint to get everything you need about a protocol in a single call.

GET/protocols/:slug/actions

List all executable actions for a protocol with parameter counts and approval requirements.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/protocols/uniswap-v3/actions

Response

200 OK

{
  "protocol": "uniswap-v3",
  "actions": [
    {
      "id": "exact_input_single",
      "name": "Exact Input Single Swap",
      "type": "swap",
      "description": "Swap an exact amount of one token for a minimum amount of another.",
      "parameters_count": 7,
      "requires_approval": true,
      "transaction_steps": 3
    },
    {
      "id": "exact_output_single",
      "name": "Exact Output Single Swap",
      "type": "swap",
      "description": "Swap tokens to receive an exact amount of the output token.",
      "parameters_count": 7,
      "requires_approval": true,
      "transaction_steps": 3
    }
  ]
}

POST/protocols/:slug/actions/:action_id/build

Build a transaction for a specific protocol action. Returns the transaction steps, gas estimates, and approval requirements.

Path Parameters

Parameter	Type	Required	Description
`slug`	string	required	Protocol identifier. Accepts generic (e.g. uniswap-v3) or chain-specific (e.g. uniswap-v3-ethereum) slugs. Generic slugs default to Ethereum.
`action_id`	string	required	Action identifier (e.g. exact_input_single)

Body Parameters (Uniswap swap example)

Parameter	Type	Required	Description
`tokenIn`	address	required	Input token contract address
`tokenOut`	address	required	Output token contract address
`fee`	uint24	required	Pool fee tier: 100, 500, 3000, or 10000
`recipient`	address	required	Address to receive output tokens
`amountIn`	uint256	required	Exact input amount in wei
`amountOutMinimum`	uint256	required	Minimum output (slippage protection)

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenOut": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "fee": "3000",
    "recipient": "0xYourWalletAddress",
    "amountIn": "1000000000",
    "amountOutMinimum": "0"
  }' \
  https://axon.nanocorp.app/api/v1/protocols/uniswap-v3/actions/exact_input_single/build

Response

200 OK

{
  "protocol": "uniswap-v3",
  "action": "exact_input_single",
  "chain_id": 1,
  "parameters": {
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenOut": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "fee": "3000",
    "recipient": "0xYourWalletAddress",
    "amountIn": "1000000000",
    "amountOutMinimum": "0"
  },
  "transaction": {
    "steps": [
      {
        "step": 1,
        "action": "check_allowance",
        "description": "Check if the router has sufficient allowance",
        "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "method": "allowance(address,address)"
      },
      {
        "step": 2,
        "action": "approve",
        "description": "Approve the swap router to spend input tokens",
        "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "method": "approve(address,uint256)"
      },
      {
        "step": 3,
        "action": "execute",
        "description": "Execute the exact input single swap",
        "to": "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
        "method": "exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))"
      }
    ],
    "estimated_gas": "185000",
    "approvals_required": [
      {
        "type": "erc20_approve",
        "token": "tokenIn",
        "spender": "swap_router_02",
        "amount": "exact_or_max"
      }
    ]
  }
}

TIPThe build endpoint validates required parameters and returns a 422 with details if any are missing. This makes it safe to call speculatively from your agent to check what's needed.

GET/chains

List all supported blockchain networks with chain IDs, native currencies, and block explorer URLs.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://axon.nanocorp.app/api/v1/chains

Response

200 OK

{
  "chains": [
    {
      "id": 1,
      "name": "ethereum",
      "network": "mainnet",
      "native_currency": { "name": "Ether", "symbol": "ETH", "decimals": 18 },
      "block_explorer": "https://etherscan.io"
    },
    {
      "id": 8453,
      "name": "base",
      "network": "mainnet",
      "native_currency": { "name": "Ether", "symbol": "ETH", "decimals": 18 },
      "block_explorer": "https://basescan.org"
    },
    {
      "id": 42161,
      "name": "arbitrum",
      "network": "mainnet",
      "native_currency": { "name": "Ether", "symbol": "ETH", "decimals": 18 },
      "block_explorer": "https://arbiscan.io"
    }
  ]
}

GET/health

Health check endpoint. No authentication required. Returns API and database status.

Request

curl https://axon.nanocorp.app/api/v1/health

Response

200 OK

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-03-07T12:00:00.000Z",
  "services": {
    "api": "ok",
    "database": "ok"
  }
}

Protocol Spec Format

Every protocol in Axon is described by a standardized JSON spec (v1.0.0). This is the machine-readable format that lets your agent understand and interact with any DeFi protocol without custom integration code.

INFOThe Axon Protocol Spec is inspired by the ERC-8004 standard for on-chain protocol metadata. Full JSON Schema available at https://axon.nanocorp.app/schemas/v1/axon-protocol-spec.schema.json

Top-Level Fields

axon_versionstring

Always "1.0.0" — the spec format version.

protocolobject

Protocol identity, chain, contracts, and links.

protocol.namestring

Human-readable protocol name (e.g. Uniswap)

protocol.slugstring

URL-safe unique identifier. Pattern: ^[a-z0-9-]+$

protocol.versionstring

Protocol version (e.g. "v3")

protocol.categoryenum

protocol.chainobject

Chain deployment info with EIP-155 chain ID

protocol.contractsobject

Key contract addresses keyed by role (e.g. swap_router, pool)

protocol.linksobject

External URLs: website, docs, github, governance

actionsarray

Available protocol operations an agent can execute.

actions[].idstring

Unique action identifier (e.g. exact_input_single, supply)

actions[].typeenum

actions[].parametersarray

Typed parameters with names, types (address, uint256, etc.), constraints, and defaults

actions[].approvalsarray

Required token approvals before execution (erc20_approve, permit2)

actions[].transaction_flowarray

Ordered steps: check → approve → execute, with Solidity method signatures

riskobject

Risk metadata for agent decision-making.

risk.audit_statusobject

Audited flag, auditor names, dates, and report links

risk.tvlobject

Current TVL in USD with source and last-updated timestamp

risk.incidentsarray

Historical security incidents with severity (critical → info)

risk.risk_scoreobject

Composite ratings: overall, smart_contract, centralization, oracle_dependence, liquidity

feesobject

Protocol fee structure.

fees.modelenum

per_trade | interest_rate | performance | flat | none

fees.tiersarray

Fee tiers with names, basis points, descriptions, and conditions

fees.gas_estimatesobject

Estimated gas costs per action (e.g. exact_input_single: 185000)

Guides

Execute a Uniswap Swap with an AI Agent

This guide walks through swapping 1000 USDC → ETH on Uniswap V3 via the Axon API. Your agent will: discover the protocol, validate parameters, and build the transaction.

Step 1: Fetch the Uniswap spec

agent.ts

const res = await fetch("https://axon.nanocorp.app/api/v1/protocols/uniswap-v3", {
  headers: { "Authorization": "Bearer " + AXON_API_KEY }
});
const spec = await res.json();

// Extract contracts and available actions
const router = spec.protocol.contracts.swap_router_02.address;
const actions = spec.actions.map(a => a.id);
console.log("Available actions:", actions);
// → ["exact_input_single", "exact_output_single"]

Step 2: Build the swap transaction

agent.ts

const USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
const WETH = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";

const buildRes = await fetch(
  "https://axon.nanocorp.app/api/v1/protocols/uniswap-v3/actions/exact_input_single/build",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + AXON_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      tokenIn: USDC,
      tokenOut: WETH,
      fee: "3000",           // 0.30% pool
      recipient: WALLET_ADDRESS,
      amountIn: "1000000000", // 1000 USDC (6 decimals)
      amountOutMinimum: "0"   // Set proper slippage in production!
    })
  }
);
const tx = await buildRes.json();
console.log("Transaction steps:", tx.transaction.steps.length);
// → 3 (check_allowance → approve → execute)

Step 3: Execute on-chain

agent.ts

// Use the transaction steps from Axon to execute via ethers/viem
for (const step of tx.transaction.steps) {
  if (step.action === "check_allowance") {
    // Read current allowance
    const allowance = await tokenContract.allowance(wallet, step.to);
    if (allowance >= amountIn) continue; // Skip approve if sufficient
  }
  if (step.action === "approve") {
    const approveTx = await tokenContract.approve(step.to, amountIn);
    await approveTx.wait();
  }
  if (step.action === "execute") {
    // Build and send the swap transaction using step.method
    const swapTx = await routerContract.exactInputSingle(params);
    const receipt = await swapTx.wait();
    console.log("Swap complete:", receipt.transactionHash);
  }
}

WARNAlways set a proper amountOutMinimum in production to protect against slippage. A value of 0 means accepting any output amount.

Supply to Aave from Your Agent

Supply USDC to Aave V3 to earn yield. Your agent will check the reserve is active, approve the pool, and deposit in a single flow.

agent.ts

// 1. Get Aave protocol spec
const spec = await fetch("https://axon.nanocorp.app/api/v1/protocols/aave-v3", {
  headers: { "Authorization": "Bearer " + AXON_API_KEY }
}).then(r => r.json());

// 2. Build the supply transaction
const buildRes = await fetch(
  "https://axon.nanocorp.app/api/v1/protocols/aave-v3/actions/supply/build",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + AXON_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      asset: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      amount: "1000000000",    // 1000 USDC
      onBehalfOf: WALLET_ADDRESS,
      referralCode: "0"
    })
  }
).then(r => r.json());

// 3. Execute the transaction steps
// Step 1: Check reserve status → getReserveConfigurationData
// Step 2: Approve pool to spend USDC → approve(address,uint256)
// Step 3: Supply to pool → supply(address,uint256,address,uint16)

console.log("Supply steps:", buildRes.transaction.steps);
console.log("Gas estimate:", buildRes.transaction.estimated_gas);
// → "250000"

TIPAfter supplying, the wallet will receive aTokens (e.g. aUSDC) which automatically accrue interest. Check the risk object in the spec to evaluate the protocol before supplying.

Bridge Tokens from Ethereum to Base

Cross-chain bridging follows the same pattern. Query the bridge protocol spec, build the transaction, and execute. Bridge specs include additional chain routing metadata.

agent.ts

// 1. List available chains
const chains = await fetch("https://axon.nanocorp.app/api/v1/chains", {
  headers: { "Authorization": "Bearer " + AXON_API_KEY }
}).then(r => r.json());

console.log("Supported chains:", chains.chains.map(c => c.name));
// → ["ethereum", "base", "arbitrum"]

// 2. Get bridge protocol spec
const bridge = await fetch("https://axon.nanocorp.app/api/v1/protocols/stargate-v2", {
  headers: { "Authorization": "Bearer " + AXON_API_KEY }
}).then(r => r.json());

// 3. Build bridge transaction
const buildRes = await fetch(
  "https://axon.nanocorp.app/api/v1/protocols/stargate-v2/actions/bridge/build",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + AXON_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      amount: "1000000000",     // 1000 USDC
      sourceChainId: 1,         // Ethereum
      destinationChainId: 8453, // Base
      recipient: WALLET_ADDRESS
    })
  }
).then(r => r.json());

// 4. Execute — same step pattern as other actions
for (const step of buildRes.transaction.steps) {
  // approve → execute bridge
}

INFOBridge protocols are being added. Currently supported chains: Ethereum, Base, Arbitrum. More bridges and chains coming soon.

SDKs & Code Snippets

Copy-paste these snippets to get started quickly. The API is simple REST — no SDK installation required.

TypeScript / Node.js

axon.ts

const AXON_API_KEY = process.env.AXON_API_KEY;
const AXON_BASE = "https://axon.nanocorp.app/api/v1";

async function axon(path: string, options?: RequestInit) {
  const res = await fetch(AXON_BASE + path, {
    ...options,
    headers: {
      "Authorization": "Bearer " + AXON_API_KEY,
      "Content-Type": "application/json",
      ...options?.headers,
    },
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.message || "Axon API error: " + res.status);
  }
  return res.json();
}

// List all protocols
const { protocols } = await axon("/protocols");

// Get a specific protocol
const uniswap = await axon("/protocols/uniswap-v3");

// List actions for a protocol
const { actions } = await axon("/protocols/aave-v3/actions");

// Build a transaction
const tx = await axon("/protocols/uniswap-v3/actions/exact_input_single/build", {
  method: "POST",
  body: JSON.stringify({
    tokenIn: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    tokenOut: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    fee: "3000",
    recipient: "0xYourWallet",
    amountIn: "1000000000",
    amountOutMinimum: "0"
  }),
});

// Get supported chains
const { chains } = await axon("/chains");

// Check usage
const { usage } = await axon("/usage");
console.log(`${usage.daily_remaining} requests remaining today`);

Python

axon.py

import os
import requests

AXON_API_KEY = os.environ["AXON_API_KEY"]
AXON_BASE = "https://axon.nanocorp.app/api/v1"

def axon(path, method="GET", json=None):
    """Make an authenticated request to the Axon API."""
    res = requests.request(
        method,
        AXON_BASE + path,
        headers={
            "Authorization": f"Bearer {AXON_API_KEY}",
            "Content-Type": "application/json",
        },
        json=json,
    )
    res.raise_for_status()
    return res.json()

# List all protocols
protocols = axon("/protocols")["protocols"]
print(f"Available: {[p['slug'] for p in protocols]}")

# Get a specific protocol
uniswap = axon("/protocols/uniswap-v3")
print(f"Actions: {[a['id'] for a in uniswap['actions']]}")

# Build a swap transaction
tx = axon(
    "/protocols/uniswap-v3/actions/exact_input_single/build",
    method="POST",
    json={
        "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "tokenOut": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "fee": "3000",
        "recipient": "0xYourWallet",
        "amountIn": "1000000000",
        "amountOutMinimum": "0",
    },
)
print(f"Steps: {len(tx['transaction']['steps'])}")

# Check usage
usage = axon("/usage")["usage"]
print(f"{usage['daily_remaining']} requests remaining today")

# Get supported chains
chains = axon("/chains")["chains"]
for chain in chains:
    print(f"  {chain['name']} (ID: {chain['id']})")

Supported Protocols

Protocols currently available through the Axon API. More are added regularly.

Protocol	Category	Chains	Actions
Uniswap V3`uniswap-v3`	DEX	ETH, Base, Arb	`exact_input_single, exact_output_single`
Aave V3`aave-v3`	Lending	ETH, Base, Arb	`supply, withdraw, borrow, repay, flash_loan`
Morpho Blue`morpho-blue`	Lending	ETH, Base, Arb	`supply, withdraw, borrow, repay`
1inch`1inch`	DEX Agg	ETH, Base, Arb	`swap`
ParaSwap`paraswap`	DEX Agg	ETH, Base, Arb	`swap`
0x`zerox`	DEX Agg	ETH, Base, Arb	`swap`
Across Bridge`across-bridge`	Bridge	ETH ↔ L2s	`bridge`
Stargate`stargate-bridge`	Bridge	ETH ↔ L2s	`bridge`
Hop Protocol`hop-bridge`	Bridge	ETH ↔ L2s	`bridge`

INFOComing soon: Compound V3, Curve Finance, Lido, GMX, Maker, Balancer, and more. Protocols are added based on agent builder demand.

Error Handling

The Axon API uses conventional HTTP status codes. All error responses include a JSON body with error and message fields.

Error Response Format

error response

{
  "error": "error_code",
  "message": "Human-readable description of what went wrong"
}

HTTP Status Codes

Code	Error	Description
`200`	`—`	Success. Response body contains the requested data.
`201`	`—`	Created. New resource (e.g. API key) was created.
`400`	`bad_request`	Invalid JSON body or malformed request.
`400`	`chain_required`	Generic slug matches multiple chains. Use a chain-specific slug (e.g. uniswap-v3-ethereum).
`401`	`unauthorized`	Missing or invalid Authorization header.
`404`	`not_found`	Protocol or action not found. Check the slug/action_id.
`409`	`conflict`	Resource already exists (e.g. free key for this email).
`422`	`validation_error`	Missing required parameters. Response includes the missing field names.
`429`	`rate_limit_exceeded`	Daily rate limit reached. Upgrade plan or wait for reset.
`500`	`internal_error`	Unexpected server error. Please retry or contact support.

Validation Error Example

When required parameters are missing from a build request, the API returns a 422 with specific details:

422 Unprocessable Entity

{
  "error": "validation_error",
  "message": "Missing required parameters",
  "missing": ["tokenIn", "amountIn"],
  "required_parameters": [
    {
      "name": "tokenIn",
      "type": "address",
      "description": "Contract address of the input token"
    },
    {
      "name": "amountIn",
      "type": "uint256",
      "description": "Exact amount of input tokens to swap (in wei)"
    }
  ]
}

Troubleshooting

Getting 401 Unauthorized

Ensure your Authorization header uses the format: Bearer ax-xxx.... The "Bearer " prefix (with space) is required.

Getting 404 on a protocol

Check the protocol slug. Use GET /protocols to see all available slugs. You can use generic slugs like 'uniswap-v3' (defaults to Ethereum mainnet) or chain-specific slugs like 'uniswap-v3-base'.

Getting 409 on key creation

You already have a free key for that email. Check your records or use a different email.

Getting 422 on build

The response body lists exactly which parameters are missing. Check the required_parameters array.

Getting 429 Rate Limited

You've exceeded your daily limit. Check GET /usage to see remaining quota. Resets at 00:00 UTC.

Build returns steps but transaction fails on-chain

Check: (1) sufficient token balance, (2) correct approval amount, (3) valid slippage params. Axon builds the TX, but on-chain state must be valid.

MCP Server

The Axon MCP (Model Context Protocol) server lets AI assistants interact with DeFi protocols directly. Connect your favorite AI tool — Claude Desktop, Claude Code, Cursor, or Windsurf — and use natural language to discover protocols, inspect available actions, and build executable transactions without writing any code.

The MCP server wraps the Axon REST API into four purpose-built tools that any MCP-compatible client can call. Your AI assistant gets structured access to the full Axon protocol registry and transaction builder.

TIPMCP lets your AI assistant call Axon tools directly. Just describe what you want in plain English — the assistant handles the rest.

Setup

Axon offers two ways to connect: a hosted remote server (recommended — zero install, always up-to-date) and a local standalone script (for offline/advanced use). Pick your AI tool below.

TIPRecommended: Use the remote MCP server at https://axon.nanocorp.app/api/mcp. No npm packages to install, no version mismatches, no build issues. It just works.

Claude Code

Add the Axon MCP server to your ~/.claude.json config file. Open it and add the following under mcpServers:

~/.claude.json

{
  "mcpServers": {
    "axon": {
      "type": "http",
      "url": "https://axon.nanocorp.app/mcp"
    }
  }
}

Then restart Claude Code. The server is hosted remotely, so there's nothing to install. Claude Code will automatically discover all four Axon tools.

INFONote: The claude mcp add --transport http CLI command has a known bug in some versions. Editing ~/.claude.json directly is the reliable method.

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

claude_desktop_config.json

{
  "mcpServers": {
    "axon": {
      "type": "url",
      "url": "https://axon.nanocorp.app/api/mcp"
    }
  }
}

Cursor

Add the following to your Cursor MCP configuration file (.cursor/mcp.json in your project root):

.cursor/mcp.json

{
  "mcpServers": {
    "axon": {
      "type": "url",
      "url": "https://axon.nanocorp.app/api/mcp"
    }
  }
}

Windsurf

Add the following to your Windsurf MCP configuration file (~/.codeium/windsurf/mcp_config.json):

mcp_config.json

{
  "mcpServers": {
    "axon": {
      "type": "url",
      "url": "https://axon.nanocorp.app/api/mcp"
    }
  }
}

INFOThe remote server works without an API key for discovery (listing protocols and tools). For building transactions and higher rate limits, generate a free key via POST /api/v1/keys or sign up at axon.nanocorp.app.

Alternative: Local Standalone Server

If you prefer to run the MCP server locally (e.g. for offline use or custom setups), download our self-contained script:

terminal

# Download the standalone server
curl -o axon-mcp-server.mjs https://axon.nanocorp.app/axon-mcp-server.mjs

# Set your API key and run it
export AXON_API_KEY="ax-your-api-key"
node axon-mcp-server.mjs

Then register it with your AI tool:

terminal

# Claude Code
claude mcp add axon -- node /path/to/axon-mcp-server.mjs

# Or add to Claude Desktop config:
# {
#   "mcpServers": {
#     "axon": {
#       "command": "node",
#       "args": ["/path/to/axon-mcp-server.mjs"],
#       "env": { "AXON_API_KEY": "ax-your-api-key" }
#     }
#   }
# }

Environment Variables

The local standalone MCP server reads the following environment variables at startup (not needed for the hosted remote server):

Variable	Required	Default	Description
`AXON_API_KEY`	recommended	--	Your Axon API key. Used to authenticate requests when running the local server.
`AXON_BASE_URL`	optional	`https://axon.nanocorp.app/api/v1`	Override the base URL for the Axon API. Useful for local development or custom deployments.

Available Tools

The Axon MCP server exposes four tools that your AI assistant can invoke:

GETlist_protocols

List all supported DeFi protocols. Returns protocol names, slugs, categories, and chain IDs. Use this to discover what protocols are available before drilling into specific actions.

Returns: Array of protocol objects with slug, name, category, and supported chains.

GETget_protocol_spec

Get the full specification for a single protocol by its slug. Includes the protocol description, ABI fragments, contract addresses, and all available actions with their parameters.

Returns: Complete protocol spec object with actions, contracts, and ABI details.

GETlist_actions

List all actions available for a specific protocol. Each action represents a single on-chain operation (e.g. swap, supply, stake) with its required and optional parameters.

Returns: Array of action objects with id, name, description, and parameter schemas.

POSTbuild_transaction

Build an executable transaction for a specific protocol action. Provide the protocol slug, action ID, and all required parameters. Returns ready-to-sign transaction calldata.

Returns: Transaction object with to, data, value, and step-by-step breakdown.

Example Prompts

Once the MCP server is connected, try these prompts with your AI assistant:

“What DeFi protocols does Axon support?”

Calls list_protocols to show all available protocols with their categories and chains.

“Show me all the actions I can do with Uniswap V3”

Calls get_protocol_spec or list_actions for uniswap-v3 to enumerate swap, add liquidity, and other operations.

“Build a transaction to swap 1000 USDC for WETH on Uniswap V3”

Calls build_transaction with the exact_input_single action and the correct token addresses and amounts.

“What parameters do I need to supply assets on Aave V3?”

Calls list_actions for aave-v3, then inspects the supply action's required parameters.

“Help me bridge 0.5 ETH from Ethereum to Arbitrum”

Discovers bridge protocols via list_protocols, inspects available actions, and builds the bridge transaction.

“Compare the available actions between Uniswap V3 and Aave V3”

Calls list_actions for both protocols and presents a side-by-side comparison.

TIPThe MCP server handles all API authentication and request formatting. Just describe your intent in natural language and the assistant will pick the right tool and parameters.

Axon API v1.0 Documentation

Home Specs Blog