API Documentation

REST API for building unsigned EVM transactions. Same PlaybookEngine as the CLI, hosted as a managed service.

Base URL: https://api-defi-skills.nethermind.io
All endpoints require Bearer token auth (API key) except GET /health. Sign in with GitHub at the Playground to generate an API key.

Quick start

Get an API key

Your API key

{
  "api_key": "aw_a1b2c3...",
  "email": "[email protected]",
  "plan": "free"
}

Save your key immediately. It cannot be retrieved again. Keys are prefixed with aw_.

Build a transaction (deterministic, no LLM)

curl -s -X POST https://api-defi-skills.nethermind.io/v1/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "aave_supply",
    "arguments": {"asset": "USDC", "amount": "500"},
    "from_address": "0xYourWallet",
    "chain_id": 1
  }'

Response

{
  "success": true,
  "transactions": [
    {
      "type": "approval",
      "token": "0xA0b8...",
      "spender": "0x8787...",
      "raw_tx": { "chain_id": 1, "to": "0xA0b8...", "value": "0", "data": "0x095ea7b3..." }
    },
    {
      "type": "action",
      "action": "aave_supply",
      "target_contract": "0x8787...",
      "function_name": "supply",
      "raw_tx": { "chain_id": 1, "to": "0x8787...", "value": "0", "data": "0x617ba037..." }
    }
  ]
}

Layer 1: Deterministic engine

These endpoints expose the PlaybookEngine directly. No LLM involved. Deterministic input/output.

GET /v1/actions

List all supported actions grouped by protocol. Pass ?chain_id= to filter by chain (default: 1).

curl -s "https://api-defi-skills.nethermind.io/v1/actions?chain_id=42161" \
  -H "Authorization: Bearer YOUR_API_KEY"

Supported chain IDs: 1 (Mainnet), 42161 (Arbitrum), 8453 (Base), 10 (Optimism), 137 (Polygon), 11155111 (Sepolia)

200 OK

{
  "actions": {
    "aave_supply": {"protocol": "aave_v3", "description": "Supply asset to Aave V3..."},
    "uniswap_swap": {"protocol": "uniswap_v3", "description": "Swap tokens via Uniswap V3..."}
  },
  "by_protocol": {
    "aave_v3": ["aave_supply", "aave_withdraw", "..."],
    "uniswap_v3": ["uniswap_swap", "uniswap_lp_mint", "..."]
  },
  "count": 25
}

GET /v1/actions/{action_name}

Get parameter schema, valid tokens, and description for a specific action. Pass ?chain_id= to check availability on a chain.

curl -s "https://api-defi-skills.nethermind.io/v1/actions/uniswap_swap?chain_id=42161" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "action": "uniswap_swap",
  "protocol": "uniswap_v3",
  "description": "Swap tokens via Uniswap V3 single-hop",
  "parameters": {
    "required": {
      "asset_in": {"type": "token_symbol", "hint": "e.g. USDC, ETH, WETH"},
      "asset_out": {"type": "token_symbol", "hint": "e.g. USDC, ETH, WETH"},
      "amount": {"type": "amount", "hint": "number as string, or \"max\""}
    },
    "optional": {
      "fee": {"type": "fee_tier", "hint": "500, 3000, or 10000 — auto-detected if omitted"},
      "to": {"type": "address_or_ens", "hint": "defaults to sender if omitted"},
      "slippage": {"type": "percentage", "hint": "e.g. \"0.5\" for 0.5%"}
    }
  },
  "valid_tokens": null,
  "example": {"action": "uniswap_swap", "arguments": {"asset_in": "WETH", "asset_out": "USDC", "amount": "0.5"}}
}

POST /v1/build

Build an unsigned transaction. Deterministic: same input always produces the same output. No LLM involved.

curl -s -X POST https://api-defi-skills.nethermind.io/v1/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "aave_supply",
    "arguments": {"asset": "USDC", "amount": "500"},
    "from_address": "0xYourWallet",
    "chain_id": 1
  }'

200 OK

{
  "success": true,
  "transactions": [
    {
      "type": "approval",
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "spender": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
      "raw_tx": {"chain_id": 1, "to": "0xA0b8...", "value": "0", "data": "0x095ea7b3..."}
    },
    {
      "type": "action",
      "action": "aave_supply",
      "raw_tx": {"chain_id": 1, "to": "0x8787...", "value": "0", "data": "0x617ba037..."}
    }
  ]
}

Health

GET /health

Check API status. No auth required.

curl -s https://api-defi-skills.nethermind.io/health

200 OK

{ "status": "ok", "actions_count": 53 }

Rate limits

Plan	Requests / Day
Free	50
Pro	1,000
Enterprise	10,000

Limits are per API key, counted daily (UTC). Exceeding returns 429.

Error codes

Code	Meaning
`401`	Invalid or missing API key
`403`	API key deactivated
`404`	Action not found
`409`	API key already exists (use /auth/rotate)
`422`	Invalid action, arguments, or from_address
`429`	Rate limit exceeded
`500`	Server error

Safety

Output is always an unsigned transaction. The API never signs or broadcasts.
No private keys are involved at any stage.
The /v1/build endpoint uses zero LLM tokens.
Always verify to, value, and data before signing.