Get Started

API Overview

Agra exposes an authenticated HTTP + WebSocket API for trading. Makers post signed orders that rest in the matching engine; takers settle them onchain. Collateral stays in the maker's wallet.

Base URL

Setting	Value
Base URL	`https://api.agra.gg`
Versioned namespace	`/v1/*`
Health check	`GET /healthz` (public, no auth)

1curl https://api.agra.gg/healthz
2# -> {"status":"ok","version":"2.0.0"}

Surface area

Markets: metadata, depth, single-market top, and bulk top-of-book.
Orders: quote, sign + submit, read, history, batch placement, cancels, and the dead-man's switch.
Trades & account: wallet trade history and the account-summary.
Referrals: code, registration status, registration, and stats.
WebSockets: public market data (/v1/ws) and market-maker quoting (/v1/mm/ws).

Conventions

Value	Encoding	Example
Amounts	Decimal strings (never JSON numbers)	`"0.98"`
Sizes	Raw integer token units (wei-style)	`"1000000000000000000"` (1.0 at 18 decimals)
Prices	Decimal ratio of quote per bond	`"0.98"`
Timestamps	Unix seconds (integers)	`1900003600`
Signed-order times	Unix second strings; EIP-712 fields `start_time` / `end_time` / `counter`	`"1900003600"`

Strings avoid floating-point precision loss.

Authentication & signing

X-API-Key gates admission to the API.
Value-bearing actions additionally require a wallet signature: EIP-712 for order placement, EIP-191 (personal_sign) for cancels and referral registration.

A leaked API key alone cannot place orders or move funds. See Authentication.

Verify quotes before signing. A signature authorizes a value transfer, so treat the quote endpoint as untrusted: confirm a quoted order matches your intent before you sign it. See Order Construction & EIP712 Signing.

Rate limits & errors

Requests are rate-limited per API key and per IP; a breach returns HTTP 429 with a back-off hint in details.retry_after_seconds. All non-2xx responses share one envelope, { status, code, response, details }, while success responses return the resource directly. See Error Handling.

Where to go next

Quickstart: install, configure, and make your first call.
Access & API Keys: obtain a key.
Environments & Networks: base URLs and supported chains.
Authentication: credentials and the signing model.
Order Construction & EIP712 Signing: build and sign an order in any language.
Maker Order Lifecycle: quote, sign, submit, end to end.