# Axon

> Agentic finance infrastructure. Secure, non-custodial on-chain vaults for autonomous AI agents. Gasless bot payments via EIP-712 intents, off-chain policy engine, 3-agent LLM verification, and native HTTP 402 support.

- **API Documentation (Swagger):** https://relay.axonfi.xyz/docs
- **OpenAPI Spec (JSON):** https://relay.axonfi.xyz/docs-json

## Actors

- **Owner** — Vault owner (ideally hardware wallet / multisig). Deploys vaults, registers bots, sets policies, withdraws funds, reviews flagged transactions.
- **Operator** — Optional hot wallet for day-to-day bot management, manual approvals of flagged payments, and policy tightening. Can pause and add bots within ceilings, but cannot loosen limits or withdraw.
- **Bot (Agent)** — Autonomous AI agent. Signs EIP-712 intents with an expiring deadline. Never holds ETH or submits transactions.
- **Relayer** — Axon's off-chain service. Validates intents, enforces policies, simulates, pays gas, and submits on-chain. Cannot forward payments without a valid bot-signed intent.

## How It Works

Bot signs an EIP-712 intent → POSTs to relayer → relayer simulates via `eth_call` → policy engine checks (spending limits, velocity, whitelist/blacklist, per-tx cap) → if threshold exceeded, 3-agent AI scan (2/3 consensus required) → approved intents submitted on-chain by relayer's Delegator → vault contract verifies bot registration + signature + deadline → executes → txHash returned.

Three on-chain execute actions:

- **executePayment()** — Direct transfer or swap-then-pay. Bot signs a PaymentIntent (recipient, token, amount, deadline, ref). Relayer handles swap routing if the vault holds a different token.
- **executeProtocol()** — DeFi protocol interactions (approve-call-revoke pattern). Bot signs an ExecuteIntent with an optional `value` field for forwarding native ETH to payable functions (WETH.deposit, Lido.submit, etc.). Supports any on-chain protocol including DEXes, lending, NFT marketplaces, and perps.
- **executeSwap()** — In-vault token rebalancing. Bot signs a SwapIntent specifying both sides of the swap: `fromToken` + `maxFromAmount` (what to sell and the cost cap) and `toToken` + `minToAmount` (what to buy and the slippage floor). Both sides are bot-signed — the relayer cannot substitute the input token or overspend beyond the bot's signed cap. Restricted by the vault's rebalance token whitelist, per-bot `maxRebalanceAmount` cap, and an oracle-based slippage guard.

Vaults can also receive funds: anyone can call `deposit(token, amount, ref)` on a vault.

## Smart Contracts

Three contracts deployed with identical bytecode across supported chains:

- **AxonVault.sol** — Per-owner vault (EIP-1167 minimal proxy clone). Holds funds (ERC-20 tokens, ERC-721 and ERC-1155 NFTs), verifies bot signatures, enforces per-tx hard cap and destination rules. Only the registered Delegator can call execute functions. Only the Owner can withdraw. Not upgradeable.
- **AxonVaultFactory.sol** — Deploys vault clones via EIP-1167 + CREATE2. Deterministic addresses: same owner + same nonce = same vault address across all chains. Call `deployVault()` to create a new vault, or `predictVaultAddress(owner, nonce)` to compute the address before deployment.
- **AxonRegistry.sol** — Axon-controlled. Maintains authorized relayers, approved swap routers, default tokens, and globally approved protocols.

### Contract Approvals — Tokens vs Protocols

There are three levels of contract approval for `executeProtocol()`:

1. **Default tokens** (AxonRegistry, global) — Common ERC-20 tokens (USDC, USDT, DAI, WETH, WBTC, etc.) are pre-approved on all vaults. Bots can call `approve()` on these tokens but nothing else — `transfer()`, `deposit()`, `withdraw()` are blocked. This enables the two-step DeFi pattern (approve token → call protocol) without the vault owner manually adding each token. **Approval rules:** the spender must be an approved protocol or swap router (arbitrary addresses are rejected on-chain), and the approve amount is capped by the bot's `maxPerTxAmount` and counts toward spending limits.

2. **Global protocols** (AxonRegistry, global) — WETH is globally approved as a protocol on all vaults. This allows bots to call any function including `deposit()` (wrap ETH) and `withdraw()` (unwrap WETH). Only simple utility contracts are globally approved to keep the attack surface small.

3. **Per-vault protocols** (AxonVault, per-vault) — DeFi protocols like Aave, Compound, Lido, Uniswap, OpenSea, and others must be approved by the vault owner via `approveProtocol()`. This is an opt-in — the owner decides which protocols their vault interacts with. Any function call is allowed on approved protocols.

### Deployed Addresses

**Mainnet (Arbitrum One + Base — same addresses via CREATE2):**
- AxonRegistry: `0xbc1b61653EDB3906310D4AC8a789E144B1C5A0Ff` ([Arbiscan](https://arbiscan.io/address/0xbc1b61653EDB3906310D4AC8a789E144B1C5A0Ff) | [BaseScan](https://basescan.org/address/0xbc1b61653EDB3906310D4AC8a789E144B1C5A0Ff))
- AxonVaultFactory: `0x271cf17A42435Dc08f320c85834C08a3cb71A10d` ([Arbiscan](https://arbiscan.io/address/0x271cf17A42435Dc08f320c85834C08a3cb71A10d) | [BaseScan](https://basescan.org/address/0x271cf17A42435Dc08f320c85834C08a3cb71A10d))
- Vault Implementation: `0x236ea8301d2fC3e177e2C198E67CAFcECE6e1ed0` ([Arbiscan](https://arbiscan.io/address/0x236ea8301d2fC3e177e2C198E67CAFcECE6e1ed0) | [BaseScan](https://basescan.org/address/0x236ea8301d2fC3e177e2C198E67CAFcECE6e1ed0))

**Testnets (Base Sepolia 84532 + Arbitrum Sepolia 421614 — same addresses via CREATE2):**
- AxonRegistry: `0xf47E517B78FA7a1045E9857CD39cDC024a1a59b4`
- AxonVaultFactory: `0x2df2982445bd4dc38d496cec621c9b514b469792`
- Vault Implementation: `0x9c427EbEBE9Acd98ac49e166E3AB159a7e1648F5`

For full contract source, structs, and interfaces → https://github.com/axonfi/core

## SDKs and Plugins

| Package                  | Registry | Install                                | GitHub                                          |
|--------------------------|----------|----------------------------------------|-------------------------------------------------|
| @axonfi/sdk              | npm      | `npm install @axonfi/sdk`              | [axonfi/sdk](https://github.com/axonfi/sdk)     |
| axonfi                   | PyPI     | `pip install axonfi`                   | [axonfi/sdk-python](https://github.com/axonfi/sdk-python) |
| langchain-axon           | PyPI     | `pip install langchain-axon`           | [axonfi/langchain-python](https://github.com/axonfi/langchain-python) |
| crewai-axon              | PyPI     | `pip install crewai-axon`              | [axonfi/plugin-crewai](https://github.com/axonfi/plugin-crewai) |
| autogen-axon             | PyPI     | `pip install autogen-axon`             | [axonfi/plugin-autogen](https://github.com/axonfi/plugin-autogen) |
| @axonfi/plugin-vercel-ai | npm      | `npm install @axonfi/plugin-vercel-ai` | [axonfi/plugin-vercel-ai](https://github.com/axonfi/plugin-vercel-ai) |
| @axonfi/plugin-elizaos   | npm      | `npm install @axonfi/plugin-elizaos`   | [axonfi/plugin-elizaos](https://github.com/axonfi/plugin-elizaos) |

## SDK (TypeScript)

```bash
npm install @axonfi/sdk
```

```typescript
import { AxonClient, Chain } from '@axonfi/sdk';

const client = new AxonClient({
  vaultAddress: '0xVAULT_ADDRESS',
  chainId: Chain.Base,
  botPrivateKey: '0xBOT_PRIVATE_KEY',
});
```

No RPC endpoint needed — the SDK signs intents locally and reads chain data through the relayer.

Before deploying a vault, the owner must accept the Terms of Service via `client.acceptTos(signer, wallet)` (wallet signature). The relayer rejects vault registration without ToS acceptance. Check status with `client.getTosStatus(wallet)`.

What you can do with the SDK:

- **Pay** — `client.pay({ to, token, amount, memo? })` — submit a payment intent
- **Execute** — `client.execute({ protocol, callData, token, amount, value? })` — DeFi protocol calls (optional `value` forwards native ETH for payable functions)
- **Swap** — `client.swap({ toToken, minToAmount, fromToken, maxFromAmount })` — in-vault rebalancing with bot-signed input bounds
- **Poll** — `client.poll(requestId)`, `client.pollExecute(requestId)`, `client.pollSwap(requestId)`
- **Read** — `client.getBalance(token)`, `client.getBalances(tokens)`, `client.getVaultInfo()`, `client.getVaultValue()` (total USD value across all holdings)
- **Check** — `client.isActive()`, `client.isPaused()`, `client.canPayTo(dest)`, `client.isContractApproved(addr)`
- **Keystore** — `encryptKeystore()` / `decryptKeystore()` for secure bot key storage
- **Constants** — `Chain`, `Token`, `KNOWN_TOKENS`, `USDC`, `WINDOW` time presets

Amounts accept human-friendly numbers (`5.2`), strings (`'5.2'`), or raw BigInt. Tokens accept symbols (`'USDC'`), enum values (`Token.USDC`), or addresses.

For full API reference → https://www.npmjs.com/package/@axonfi/sdk

## API

Full OpenAPI/Swagger documentation → **https://relay.axonfi.xyz/docs**

No authentication required — authorization comes from the bot's EIP-712 signature and on-chain registration.

Endpoint groups:

- **Payments** — Submit payment intents, poll status, batch lookup by tx hash
- **Protocol Execution** — Submit DeFi protocol calls, poll status
- **Swaps / Rebalancing** — Submit in-vault rebalances, poll status
- **Vault Reads** — Token balances, vault info, bot status, destination checks, rebalance token whitelist
- **Info** — Supported chains and tokens (`GET /v1/chains`), service health

All submit endpoints accept `simulate: true` for dry-run validation (full policy checks + simulation without broadcasting).

Response paths: **fast** (sync txHash) | **AI scan** (~30s when AI threshold triggered) | **human review** (async `requestId` — poll until resolved).

For detailed endpoints, request/response schemas, parameters, and error codes → https://relay.axonfi.xyz/docs

## Policy Engine

Owner-configured rules enforced by the relayer. Configuration stored on-chain in BotConfig structs for verifiability.

- Per-bot spending limits: up to 5 time windows. Only fixed durations are allowed: 1h (3600s), 3h (10800s), 24h (86400s), 7d (604800s), 30d (2592000s). Each window has amount + count caps
- Hard per-transaction cap (`maxPerTxAmount`) — enforced on-chain, cannot be bypassed
- Destination whitelist (global vault + per-bot) and blacklist (vault-level, always wins)
- Velocity checks for unusual transaction patterns
- Configurable AI verification threshold per bot

## Swap Slippage Guard

Every vault has an on-chain oracle-based slippage guard for `executeSwap()`. It compares the USD value of tokens sold vs. tokens received using a Uniswap V3 TWAP oracle.

- **Default: 9500 (95%)** — set automatically when the vault is created via `initialize()`. This means swaps must retain at least 95% of USD value (max 5% slippage).
- **Stored per vault** in `maxSwapSlippageBps` (not on the registry — each vault has its own setting).
- **Owner-configurable** via `setMaxSwapSlippageBps(bps)`. For example, `9000` = max 10% slippage. Set to `0` to disable the oracle check entirely.
- **Graceful fallback** — if the oracle can't price either token (no Uniswap pool, stale data), the check is silently skipped and an `OracleCheckSkipped` event is emitted. The swap still executes.
- **Defense-in-depth** — the primary protection is the bot-signed `fromToken` and `maxFromAmount` fields, which cap what the vault can spend. The oracle slippage guard is an additional safety layer.
- **Preview function** — `previewSwapSlippage(fromToken, fromAmount, toToken, toAmount)` lets you check whether a swap would pass before submitting.

This guard only applies to `executeSwap()` (in-vault rebalancing). It does not apply to swap routing within `executePayment()`, which is a different flow.

## AI Verification

Payments exceeding a bot's AI threshold trigger three independent LLM agents in parallel: a **Safety Agent** (destination analysis, threat signals), a **Behavioral Agent** (anomaly detection against historical patterns), and a **Reasoning Agent** (prompt injection / social engineering detection). A 2/3 consensus is required to approve. Without consensus, the transaction enters a human review queue with push notification and Telegram alerts to the owner.

Rejected transactions create vault-scoped threat signals that feed into future AI scanning. Threat signals auto-deactivate if the owner later approves a similar transaction, preventing permanent false positives.

## Security Model

- **Non-custodial**: Only the Owner wallet can withdraw funds — enforced in Solidity, not a policy setting.
- **Owner sovereignty**: If Axon goes offline, the Owner can call `withdraw()` directly on the contract from any Ethereum client. Zero dependency on Axon infrastructure for fund recovery.
- **Bounded bot compromise**: A compromised bot key can only sign intents within its configured limits. Signatures expire in ≤15 minutes. Owner can remove the bot instantly.
- **Operator constraints**: Cannot loosen policies, cannot withdraw, cannot unpause. Bounded impact if compromised.
- **Relayer is facilitation only**: Pays gas and submits transactions, but cannot fabricate payments without a valid bot signature.

## NFT Support

Vaults natively hold ERC-721 and ERC-1155 NFTs (implements `onERC721Received` and `onERC1155Received`). Bots can interact with NFT marketplaces and protocols via `executeProtocol()`. NFT operations are subject to enhanced screening — approvals and high-value transfers receive additional verification before execution. Only the Owner can withdraw NFTs from the vault.

Vaults implement ERC-1271 (`isValidSignature`), enabling bots to create valid off-chain signatures on behalf of the vault. This supports NFT listings on Seaport/OpenSea/Blur, limit orders on Cowswap/1inch/0x, Permit2 signature-based transfers, and other signature-validation protocols. Signatures from the vault owner or any active registered bot are accepted.

## Examples

Ready-to-run examples in TypeScript and Python → https://github.com/axonfi/examples

- **vault-setup** — Deploy a vault and register a bot
- **swap-and-pay** — Swap tokens and make payments
- **opensea-buy** — Buy NFTs from OpenSea via Seaport into your vault
- **nft-mint** — Mint NFTs via executeProtocol()
- **aave-lending** — Supply and withdraw from Aave V3
- **uniswap-lp** — Provide liquidity on Uniswap V3
- **ostium-perps-trader** — Open perpetual positions on Ostium
- **express-402-server** — HTTP 402 payment server with Express
- **elizaos-agent** — ElizaOS agent with Axon plugin
- **langchain-api-agent** — LangChain agent with Axon tools
- **crewai-research-agent** — CrewAI multi-agent with payments (Python)
- **scheduled-payments** — Cron-based recurring payments (Python)
- **batch-payments** — Parallel batch payments (TypeScript)
- **cli-payments** — Interactive CLI payment tool (Python)
- **defi-trading-agent** — Autonomous DeFi trading agent (Python)
- **weth-wrap** — ETH→WETH wrapping via WETH.deposit() with value
- **lido-stake** — Lido staking (L1 direct or L2 DEX swap)
- **vault-rebalance** — In-vault USDC→WETH swap via executeSwap() with bot-signed fromToken/maxFromAmount
- **seaport-listing** — NFT listing via ERC-1271 vault signatures

## Chains and Tokens

**Live chains:** Arbitrum One (42161), Base (8453), Base Sepolia (84532), Arbitrum Sepolia (421614).

USDC is the base asset. Any ERC-20 token can be used as payment output — the relayer swaps atomically via approved DEX routers.

## Links

- Website: https://axonfi.xyz
- Dashboard: https://app.axonfi.xyz
- API Documentation (Swagger): https://relay.axonfi.xyz/docs
- Blog: https://dev.to/axonfi
- SDK (TypeScript): https://github.com/axonfi/sdk
- SDK (Python): https://github.com/axonfi/sdk-python
- Smart Contracts: https://github.com/axonfi/core
- Examples: https://github.com/axonfi/examples
- LangChain Plugin: https://github.com/axonfi/langchain-python
- CrewAI Plugin: https://github.com/axonfi/plugin-crewai
- AutoGen Plugin: https://github.com/axonfi/plugin-autogen
- Vercel AI Plugin: https://github.com/axonfi/plugin-vercel-ai
- ElizaOS Plugin: https://github.com/axonfi/plugin-elizaos
- GitHub: https://github.com/axonfi
- Twitter / X: https://x.com/axonfixyz
- Contact: hello@axonfi.xyz