@aiignotusBack to home

Agent API Overview

Agent API

A production‑grade API for autonomous onchain actions. The Agent API is designed for agentic workflows that require natural language → onchain execution with strict control, clear observability, and safe defaults.

What you can do:

  • Parse intent and generate quotes
  • Resolve tokens (symbols, tickers, addresses)
  • Analyze wallets and balances
  • Execute swaps and transfers via agent wallets
  • Build and submit limit orders

Security model:

  • One API key per agent (required for /agent/* endpoints)

Who it’s for:

  • AI agents that need reliable, structured onchain actions
  • Apps that want a single endpoint for natural language execution
  • Teams that need safety, auditability, and deterministic outputs

Architecture at a glance

The API is split into two layers:

1) Non‑custodial endpoints Return transaction data or read‑only information. You sign & broadcast externally.

2) Agent execution endpoints Use Coinbase CDP wallets to sign and broadcast server‑side, enabling full automation.

Guarantees

  • Consistent error format with request IDs
  • Chain‑aware token resolution
  • Deterministic JSON responses
  • Clean separation of quote vs execution

Recommended next steps

  • Start with the Quickstart
  • Try the 60‑second demo
  • Explore /agent/execute in depth

Quickstart

Quickstart

Install + run

cd agent-api
cp .env.example .env
npm install
npm run dev

Server runs on https://api.ignotusai.xyz.

Required environment variables

PORT=4010
OPENAI_API_KEY=your-key
REQUIRE_API_KEY=false
API_KEY=your-secret
REQUIRE_AGENT_KEY=true

BASE_RPC_URL=...
ETHEREUM_RPC_URL=...
OPTIMISM_RPC_URL=...
ARBITRUM_RPC_URL=...
BSC_RPC_URL=...

CDP_API_KEY_ID=...
CDP_API_KEY_SECRET=...
CDP_WALLET_SECRET=...
CDP_NETWORK_ID=base

Health check

curl -s https://api.ignotusai.xyz/health | jq

First autonomous action

1) Create an agent API key

curl -s https://api.ignotusai.xyz/agent/keys/create \
  -H "Content-Type: application/json" \
  -d '{"agentId":"demo-agent"}' | jq

2) Execute

curl -s https://api.ignotusai.xyz/agent/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_..." \
  -d '{"agentId":"demo-agent","prompt":"Swap 50% of my ETH to USDC on Base","chain":"base","slippageBps":50}' | jq

/agent/execute

/agent/execute — Natural Language → Onchain

POST /agent/execute is the core endpoint for autonomous execution. It can resolve tokens, compute balances, get quotes, sign, and broadcast — all from a single prompt.

Request

{
  "agentId": "agent-001",
  "walletNo": 1,
  "prompt": "Swap 50% of my ETH to USDC on Base",
  "chain": "base",
  "slippageBps": 50
}

Send the agent API key in the header:

X-API-Key: ak_...

Supported prompts

  • Swaps: “swap 0.1 eth to usdc”
  • Percentages: “swap 50% of my eth to degen”
  • USD amounts: “swap $5 worth of eth to usdc”
  • Transfers (ETH): “transfer $1 of eth to 0x…”
  • Transfers (ERC‑20): “transfer all my degen to 0x…”
  • Token resolve: “what’s the CA for $DEGEN?”
  • Balances: “check my degen balance”

Response (example)

{
  "wallet": {"agentId":"agent-001","address":"0x...","networkId":"base"},
  "response": "Swap executed successfully.",
  "toolResults": [
    {"toolName":"resolve_token", "result": {"token": {"symbol": "DEGEN"}}},
    {"toolName":"execute_swap", "result": {"txHash":"0x..."}}
  ]
}

Notes

  • Transactions are signed via CDP wallet provider.
  • The agent wallet must have sufficient ETH for gas and token balances.
  • You can layer policies (spend caps, token allowlists) at the API layer for production safety.

Multiple wallets

Each agent can own multiple wallets. Use walletNo to select which wallet to operate with. If omitted, the default wallet (walletNo: 1) is used.

API Reference

API Reference

Core

  • GET /health
  • GET /chains

Intent

  • POST /intents/parse
  • POST /intents/execute

Tokens

  • POST /tokens/resolve

Quotes

  • POST /quotes/swap
  • POST /quotes/bridge

Wallets

  • POST /wallet/analyze
  • POST /wallet/balance

Transactions

  • POST /tx/broadcast
  • GET /tx/:hash

Orders

  • POST /orders/limit/build
  • POST /orders/limit/submit
  • GET /orders/limit/:id
  • POST /orders/limit/:id/cancel

Agent

  • POST /agent/keys/create
  • GET /agent/keys/:agentId
  • POST /agent/wallets/create
  • GET /agent/wallets/:agentId
  • GET /agent/wallets/:agentId/list
  • POST /agent/execute

OpenAPI

A full OpenAPI spec is available in docs/agent-api/openapi.yaml.

Security & Production Hardening

Security & Production Hardening

Authentication

Enable admin API key auth in production (optional):

REQUIRE_API_KEY=true
API_KEY=your-secret

Then send:

X-API-Key: your-secret

Per-agent API keys

Each agent has its own API key. This key is required for all /agent/* endpoints when REQUIRE_AGENT_KEY=true.

Create a key:

curl -s https://api.ignotusai.xyz/agent/keys/create \
  -H "Content-Type: application/json" \
  -d '{"agentId":"agent-001"}' | jq

Use it on agent calls:

X-API-Key: ak_...

Note: When REQUIRE_API_KEY=true, the admin key protects non‑agent endpoints.

Recommended protections

  • Policy engine: per‑agent allowlists, max spend, max slippage
  • Nonce locking: prevent double‑spends on rapid calls
  • Rate limiting: global, per‑agent, per‑endpoint
  • Audit logs: store all requests, tool calls, and tx hashes
  • Pre‑trade simulation: callStatic/eth_call before sending
  • Approval safeguards: cap ERC‑20 approvals

Rate limiting (built‑in)

Ignotus ships with production‑ready rate limits to protect from abuse:

  • Global per‑IP: 120 req/min
  • Per‑agent: 60 req/min
  • Wallet creation: 5 req/min per agent, 10 req/min per IP
  • Agent key creation: 5 req/hour per IP

Tune via environment variables:

RATE_LIMIT_GLOBAL_WINDOW_MS=60000
RATE_LIMIT_GLOBAL_MAX=120
RATE_LIMIT_AGENT_WINDOW_MS=60000
RATE_LIMIT_AGENT_MAX=60
RATE_LIMIT_WALLET_CREATE_WINDOW_MS=60000
RATE_LIMIT_WALLET_CREATE_MAX=5
RATE_LIMIT_WALLET_CREATE_IP_WINDOW_MS=60000
RATE_LIMIT_WALLET_CREATE_IP_MAX=10
RATE_LIMIT_KEYS_CREATE_WINDOW_MS=3600000
RATE_LIMIT_KEYS_CREATE_MAX=5

When limits are exceeded, the API returns 429 with Retry-After and X-RateLimit-* headers.

Wallet caps

Each agent can only create a fixed number of wallets. Default:

  • MAX_WALLETS_PER_AGENT=5

Requests beyond the limit return 403 WALLET_LIMIT.

Wallet custody model

  • /agent/execute signs via Coinbase CDP wallet provider
  • You do not hold raw private keys
  • CDP credentials must be treated as production secrets

60‑Second Demo

60‑Second Demo

This demo creates an agent wallet, waits for funding, then executes a swap using /agent/execute.

cd /Users/mannugaddhyan/privacy-swap-ai
npx tsx scripts/demo-agent-execute.ts \
  --agentId demo-agent \
  --chain base \
  --minEth 0.003 \
  --prompt "Swap 50% of my ETH to USDC on Base"

What happens:

  1. A wallet is created via /agent/wallets/create
  2. The script prints the address
  3. You fund it with ETH
  4. The agent executes the swap and returns a tx hash

Note: If REQUIRE_AGENT_KEY=true, create the agent key first:

curl -s https://api.ignotusai.xyz/agent/keys/create \
  -H "Content-Type: application/json" \
  -d '{"agentId":"demo-agent"}' | jq

Or pass it directly:

AGENT_API_KEY=ak_... npx tsx scripts/demo-agent-execute.ts --agentId demo-agent

Live Demo

Agent executes a real onchain swap, no UI, no clicks

Watch the full flow: the agent reads the API docs, creates a wallet, waits for funding, then swaps on Base — all from natural language.

Watch the 60‑second demo