AxonAxon

API Overview

Base URLs, authentication, rate limits, and conventions for the Axon relayer API.

API Overview

The Axon relayer exposes a REST API for submitting payment intents and querying payment status. Every SDK and framework plugin is built on top of this API. You can call it directly from any language that supports HTTP requests and EIP-712 signing.

Base URL

EnvironmentURL
Productionhttps://relay.axonfi.xyz
Local developmenthttp://localhost:3000

All endpoints are versioned under /v1.

Authentication

The Axon API does not use API keys or bearer tokens for payment submission. Instead, authentication is cryptographic: every payment request includes an EIP-712 signed intent from a bot whose address is whitelisted on the target vault.

The relayer verifies:

  1. The EIP-712 signature is valid for the given intent
  2. The recovered signer address matches the bot field
  3. The bot is active (whitelisted) on the vault contract
  4. The intent deadline has not expired

This means any process that holds a bot's private key can submit payments -- no additional credentials needed.

Future API endpoints (e.g. dashboard-facing routes for querying vault state) may require separate authentication. This page covers the payment submission API used by bots.

Content Type

All requests and responses use JSON:

Content-Type: application/json

Idempotency

Every POST /v1/payments request requires an idempotencyKey field in the request body. This must be a UUID (v4 recommended).

If the relayer receives a request with an idempotencyKey it has seen before, it returns the original response without re-executing the payment. This makes retries safe in unreliable network conditions.

You may also pass the key as an HTTP header:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

If both the header and body field are present, the body field takes precedence.

Always generate a new UUID for each distinct payment. Reusing an idempotency key for a different payment intent will return the cached result of the first payment, not execute the new one.

Rate Limits

Rate limits are applied per bot address and per vault. Specific limits will be published before mainnet launch. During testnet, generous defaults are in place to support development.

Rate-limited responses return HTTP 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Request Format

curl -X POST https://relay.axonfi.xyz/v1/payments \
  -H "Content-Type: application/json" \
  -d '{
    "bot": "0xBotAddress",
    "to": "0xRecipient",
    "token": "0xUSDCAddress",
    "amount": "10000000",
    "deadline": "1740200000",
    "ref": "0x...",
    "signature": "0x...",
    "chainId": 8453,
    "vaultAddress": "0xVaultAddress",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response Format

All successful responses return JSON with an HTTP 200 status:

{
  "requestId": "req_abc123",
  "status": "approved",
  "txHash": "0x..."
}

Error responses use standard HTTP status codes with a consistent error body:

{
  "error": "Invalid signature",
  "code": "INVALID_SIGNATURE",
  "details": "Recovered signer 0x... does not match bot field 0x..."
}

See Error Codes for the full list.

Endpoints

MethodPathDescription
POST/v1/paymentsSubmit a payment intent
GET/v1/payments/:requestIdCheck payment status
POST/v1/executeSubmit a DeFi protocol execution intent
GET/v1/execute/:requestIdCheck protocol execution status
POST/v1/swapSubmit an in-vault rebalancing swap intent
GET/v1/swap/:requestIdCheck rebalancing swap status
GET/v1/vault/:address/rebalance-tokensGet effective rebalance token whitelist for a vault
GET/v1/vault/:address/rebalance-token/:tokenCheck if a token is allowed for rebalancing

Next Steps