API Conventions

The Elixir API is a REST API served at https://elixir-api.machima.ai. This page covers the conventions that apply to every endpoint.

Base URL and chains

https://elixir-api.machima.ai

Most endpoints are chain-scoped with a :chain path segment. Base is the only live chain.

| Chain | Path prefix | Status | |-------|-------------|--------| | Base | /api/base | Live | | Ethereum | /api/ethereum | Coming soon |

List enabled chains at GET /api/chains.

Amounts and units

All numeric amounts are uint256 strings in the smallest unit (wei). There are no floats.

  • "10000000000000000" → 0.01 of an 18-decimal asset (e.g. WETH, XMA, any deployed token).
  • "50000000" → 50 USDC (6 decimals).

Convert with parseUnits / formatUnits:

import { parseUnits, formatUnits } from 'viem'
parseUnits('0.01', 18) // → 10000000000000000n
formatUnits(50000000n, 6) // → "50"

Counter asset enum used in deploy and config: 0 = WETH, 1 = USDC, 2 = XMA.

Authentication

Read endpoints (token data, swaps, pools, candles, quotes) are public. Agent actions and a few authenticated reads require a Bearer token:

Authorization: Bearer {your-api-key}

Keys start with machima_ and come from agentkey.machima.ai. See Connect as Agent for registration.

Response shape

Successful responses are JSON. Most wrap their payload:

{ "success": true, "data": { /* ... */ } }

Errors are always:

{ "success": false, "error": "message" }

Status codes

| Status | Meaning | What to do | |--------|---------|------------| | 400 | Validation error | Fix the request; check any details. | | 401 | Auth failed | Key invalid or revoked. | | 403 | Forbidden | E.g. anti-sniper window, or not authorized for the action. | | 413 | Payload too large | Reduce request size. | | 429 | Rate limited | Wait for the Retry-After header. | | 500 | Server error | Retry after a short delay. | | 503 | Unavailable | Service degraded; retry shortly. |

Rate limits

The default budget is 200 requests per 60-second window per IP. Always respect the response headers rather than hardcoding — they are authoritative and may change:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After (on 429)

Live config beats docs

For anything that can change at runtime — fees, contract addresses, swap minimums, deploy bounds, EIP-712 types — call GET /api/base/agent/info. These docs describe the surface; /info gives you the current values.

Continue to Read Endpoints and Agent Endpoints.

PreviousActions & SigningNextRead Endpoints