A standardized JSON schema that describes any DeFi protocol in a format AI agents can parse, reason about, and execute against.
How Agents Use Specs
Schema Anatomy
Each Axon spec is a complete, self-contained description of a DeFi protocol that an AI agent can use to discover capabilities, validate parameters, assess risk, and construct transactions.
Name, chain, version, verified contract addresses, and links.
Every operation an agent can execute — typed parameters with constraints.
Audit status, TVL, historical incidents, and composite risk scores.
Fee models, tier breakdowns in basis points, and gas estimates.
Step-by-step approval and execution instructions with Solidity signatures.
Live Examples
Browse the formal schema definition, then explore populated specs for Uniswap V3, Aave V3, and DEX aggregators like 1inch — the exact format your agent consumes via the API.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://axon.nanocorp.app/schemas/v1/axon-protocol-spec.schema.json",
"title": "Axon Protocol Spec",
"description": "Machine-readable specification for DeFi protocols, enabling AI agents to discover, understand, and interact with on-chain protocols.",
"version": "1.0.0",
"type": "object",
"required": ["axon_version", "protocol", "actions", "risk", "fees"],
"properties": {
"axon_version": {
"type": "string",
"const": "1.0.0",
"description": "Version of the Axon Protocol Spec format"
},
"protocol": {
"type": "object",
"description": "Protocol identity and deployment information",
"required": ["name", "slug", "version", "chain", "contracts"],
"properties": {
"name": { "type": "string", "description": "Human-readable protocol name" },
"slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "description": "URL-safe unique identifier" },
"version": { "type": "string", "description": "Protocol version (e.g. v3)" },
"description": { "type": "string", "description": "Brief protocol description" },
"category": {
"type": "string",
"enum": ["dex", "lending", "staking", "yield", "derivatives", "bridge", "other"]
},
"chain": {
"type": "object",
"required": ["id", "name"],
"properties": {
"id": { "type": "integer", "description": "EIP-155 chain ID" },
"name": { "type": "string" },
"network": { "type": "string", "enum": ["mainnet", "testnet"] }
}
},
"contracts": {
"type": "object",
"description": "Key contract addresses keyed by role",
"additionalProperties": {
"type": "object",
"properties": {
"address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
"label": { "type": "string" },
"verified": { "type": "boolean" }
},
"required": ["address"]
}
},
"links": {
"type": "object",
"properties": {
"website": { "type": "string", "format": "uri" },
"docs": { "type": "string", "format": "uri" },
"github": { "type": "string", "format": "uri" },
"governance": { "type": "string", "format": "uri" }
}
}
}
},
"actions": {
"type": "array",
"description": "Available protocol operations an agent can execute",
"items": {
"type": "object",
"required": ["id", "name", "type", "parameters", "transaction_flow"],
"properties": {
"id": { "type": "string", "description": "Unique action identifier" },
"name": { "type": "string", "description": "Human-readable action name" },
"description": { "type": "string" },
"type": {
"type": "string",
"enum": ["swap", "supply", "borrow", "repay", "withdraw", "stake", "unstake", "claim", "bridge", "wrap"]
},
"parameters": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "type", "required"],
"properties": {
"name": { "type": "string" },
"type": {
"type": "string",
"enum": ["address", "uint256", "uint24", "uint16", "bytes", "bool", "string"]
},
"required": { "type": "boolean" },
"description": { "type": "string" },
"default": {},
"constraints": {
"type": "object",
"properties": {
"min": { "type": "string" },
"max": { "type": "string" },
"enum": { "type": "array" },
"pattern": { "type": "string" }
}
}
}
}
},
"constraints": {
"type": "object",
"properties": {
"min_amount": { "type": "string" },
"max_slippage_bps": { "type": "integer" },
"deadline_required": { "type": "boolean" },
"supported_tokens": { "type": "string" },
"requires_position": { "type": "boolean" }
}
},
"approvals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": { "type": "string", "enum": ["erc20_approve", "permit2", "erc721_approve"] },
"token": { "type": "string", "description": "Parameter name referencing the token" },
"spender": { "type": "string", "description": "Contract key from protocol.contracts" },
"amount": { "type": "string", "enum": ["exact", "unlimited", "exact_or_max"] }
}
}
},
"transaction_flow": {
"type": "array",
"description": "Ordered steps to execute this action",
"items": {
"type": "object",
"required": ["step", "action", "contract", "method"],
"properties": {
"step": { "type": "integer" },
"action": { "type": "string" },
"description": { "type": "string" },
"contract": { "type": "string" },
"method": { "type": "string", "description": "Solidity function signature" },
"conditional": { "type": "string" },
"returns": { "type": "array", "items": { "type": "string" } }
}
}
}
}
}
},
"risk": {
"type": "object",
"description": "Risk metadata for agent decision-making",
"properties": {
"audit_status": {
"type": "object",
"properties": {
"audited": { "type": "boolean" },
"auditors": { "type": "array", "items": { "type": "string" } },
"last_audit_date": { "type": "string", "format": "date" },
"audit_reports": { "type": "array", "items": { "type": "string", "format": "uri" } }
}
},
"tvl": {
"type": "object",
"properties": {
"current_usd": { "type": "number" },
"source": { "type": "string" },
"last_updated": { "type": "string", "format": "date-time" }
}
},
"incidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": { "type": "string", "format": "date" },
"severity": { "type": "string", "enum": ["critical", "high", "medium", "low", "info"] },
"title": { "type": "string" },
"description": { "type": "string" },
"resolved": { "type": "boolean" },
"post_mortem": { "type": "string", "format": "uri" }
}
}
},
"risk_score": {
"type": "object",
"description": "Axon risk ratings (A+ to F)",
"properties": {
"overall": { "type": "string", "enum": ["A+", "A", "B+", "B", "C", "D", "F"] },
"smart_contract": { "type": "string" },
"centralization": { "type": "string" },
"oracle_dependence": { "type": "string" },
"liquidity": { "type": "string" }
}
}
}
},
"fees": {
"type": "object",
"description": "Protocol fee structure",
"properties": {
"model": { "type": "string", "enum": ["per_trade", "interest_rate", "performance", "flat", "none"] },
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"fee_bps": { "type": ["integer", "null"], "description": "Fee in basis points" },
"description": { "type": "string" },
"conditions": { "type": "string" }
}
}
},
"gas_estimates": {
"type": "object",
"description": "Estimated gas costs per action",
"additionalProperties": { "type": "string" }
}
}
}
}
}API Reference
Every protocol spec is available via our REST API. AI agents can discover available protocols, fetch full specs, or request minimal payloads optimized for token-efficient LLM consumption.
List all available protocol specs with metadata and URLs.
{
"axon_version": "1.0.0",
"available_chains": ["ethereum", "base", "arbitrum"],
"multi_chain_protocols": [{
"family": "aave-v3",
"chains": [
{ "chain": "ethereum", "chainId": 1 },
{ "chain": "base", "chainId": 8453 },
{ "chain": "arbitrum", "chainId": 42161 }
]
}],
"available_specs": [
{ "slug": "uniswap-v3", "category": "dex", "chain": "ethereum" },
{ "slug": "aave-v3-ethereum", "category": "lending", "chain": "ethereum" },
{ "slug": "1inch-ethereum", "category": "dex", "chain": "ethereum" },
{ "slug": "zerox-ethereum", "category": "dex", "chain": "ethereum" },
{ "slug": "paraswap-ethereum", "category": "dex", "chain": "ethereum" },
"... + more"
]
}Fetch the complete protocol spec with all actions, risk data, and fees.
{
"axon_version": "1.0.0",
"protocol": {
"name": "Uniswap",
"slug": "uniswap-v3",
"version": "v3",
"category": "dex",
...
},
"actions": [ ... ],
"risk": { ... },
"fees": { ... }
}Token-efficient format — contracts, actions, transaction flows, and fees. Ideal for LLM context windows. Works with any chain variant.
{
"protocol": {
"name": "Aave",
"slug": "aave-v3-base",
"chain": { "id": 8453, "name": "base" },
"contracts": {
"pool": { "address": "0xA238Dd80C..." }
}
},
"actions": [
{ "id": "supply", "type": "supply", ... },
{ "id": "withdraw", "type": "withdraw", ... },
{ "id": "borrow", "type": "borrow", ... },
{ "id": "repay", "type": "repay", ... },
{ "id": "flash_loan", "type": "supply", ... }
]
}Raw JSON files served from CDN. Use for caching, bundling, or direct imports in your agent codebase.
% Total % Received % Xferd 100 4.2k 100 4.2k 0 0 28.0k 0 --:--:-- --:--:-- Saved: uniswap-v3.json (4.2 KB)
Integrate Axon specs into your AI agent in three lines of code.
import requests
# Fetch the Uniswap V3 spec
spec = requests.get(
"https://axon.nanocorp.app/api/specs",
params={"protocol": "uniswap-v3"}
).json()
# Your agent now knows everything about Uniswap V3
for action in spec["actions"]:
print(f"Action: {action['name']}")
print(f" Type: {action['type']}")
print(f" Params: {[p['name'] for p in action['parameters']]}")
print(f" Steps: {len(action['transaction_flow'])}")
# Check risk before executing
risk = spec["risk"]["risk_score"]
if risk["overall"] in ["A+", "A"]:
print("Protocol is safe to interact with")
# Build transaction from spec
swap = spec["actions"][0]
tx_flow = swap["transaction_flow"]
for step in tx_flow:
print(f"Step {step['step']}: {step['action']}")
print(f" Contract: {step['contract']}")
print(f" Method: {step['method']}")Get early access to the Axon SDK and start building AI agents that can interact with any DeFi protocol through a single, typed interface.