API basics tier · Reference card · API Academy

API basics.
One sheet.

Auth headers, the four core endpoints, order-status enum, position fields, decimal-units gotchas, and the error codes you’ll actually hit. Pin it; print it; come back to it.

Back to Module 06

Authentication: every request is HMAC-signed.

Every authenticated call carries three headers, lmts-api-key + lmts-timestamp + lmts-signature, computed per the scheme at docs.limitless.exchange/developers/authentication. The legacy X-API-Key header is deprecated and no longer issued to new users.

Authentication

M03

HMAC-signed on every authenticated call. Three headers, with EIP-712 wallet sig added for state-changing POSTs.

// Every authenticated request GET /portfolio/positions lmts-api-key: <apiKey / token id> lmts-timestamp: 2026-05-07T18:23:11.482Z lmts-signature: <base64 HMAC-SHA256> // State-changing requests POST /orders lmts-api-key: <apiKey> lmts-timestamp: … lmts-signature: … X-Wallet-Signature: 0xabc… X-Wallet-Nonce: 1714683600

HMAC headers prove the request, signed with your token secret, came from you. Wallet signature proves intent to move funds on-chain. Reads need only HMAC; orders need HMAC + wallet sig.

// Canonical signing string (what you HMAC) {ts}\n{METHOD}\n{path?query}\n{body} // HMAC-SHA256, base64-decoded secret, base64-encoded result sig = base64(HMAC_SHA256(base64_decode(secret), msg))

Body is the raw JSON for POSTs, an empty string for GET / DELETE. Server tolerates 30 s of clock skew, see docs.limitless.exchange/developers/authentication.

Core endpoints

M03–06

Method	Path	Returns	Module
GET	/markets	Active markets	M04
GET	/markets/{slug}	One market · metadata + book	M04
POST	/orders	Place order · needs wallet sig	M05
DELETE	/orders/{id}	Cancel order · needs wallet sig	M05
GET	/portfolio/positions	CLOB + AMM positions, points, rewards	M06
GET	/portfolio/trades	AMM fills · one call, no pagination	M06

Order status enum

M05

`pending`	signed, not yet on book
`open`	resting on book
`partial`	some shares filled
`filled`	fully executed
`cancelled`	you cancelled it
`expired`	TTL elapsed
`rejected`	signature/nonce/balance fail

Default poll interval. 1s for pending/open, 5s for partial, stop on filled/cancelled/rejected.

Order side & type

M05

Field	Values
side	buy · sell
outcome	yes · no
type	limit · market
tif	gtc · ioc · fok

Default. Limit + GTC. Switch to market only when seconds matter; switch to IOC when partial fills are unacceptable.

Position fields

M06

`cost`	USDC paid in (6 dec)
`marketValue`	USDC if closed now (6 dec)
`tokensBalance`	outcome tokens (18 dec)
`avgPrice`	USDC per share
`realizedPnl`	closed cash flow
`unrealizedPnl`	marketValue − cost

Watch decimals. USDC = 6, outcome tokens = 18. Mixing them is the most common silent bug.

Decimal units

M06

Asset	Decimals	Divisor
USDC	6	1e6
Outcome tokens	18	1e18
ETH	18	1e18
WBTC	8	1e8

// Helper. Always. fromUnits(amt, dec) => Number(amt) / 10 ** dec

PnL formulas

M06

Realised · from fills, deterministic.

realised = Σ (sell_flow) − Σ (buy_flow) − Σ (fees)

Unrealised · from open positions, live.

unrealised = (mark − avgEntry) × openSize

Total PnL = realised + unrealised. Quote unrealised with a timestamp; it’s a snapshot.

Errors you’ll actually hit

Cross-module

Code	Meaning	Fix
`401`	Invalid API key or expired wallet sig	Re-sign · check key in `.env`
`409`	Nonce already used	Refresh nonce; never reuse
`422`	Bad order shape (price out of range, etc.)	Validate before signing
`429`	Rate limited	Backoff with jitter; cache reads
`503`	Indexer behind	Retry with exp backoff; reconcile on chain

Idempotency. Always include a client-side nonce on POSTs. If the server returns 5xx, you can safely retry with the same nonce, the server dedupes.

Pitfalls that bite production bots

Cross-module

Mixing decimal precisions. USDC at 1e6 next to outcome tokens at 1e18. Build fromUnits(), never inline divisors.
Reading positions immediately after a fill. Indexer lag is 1–5s. Trust the order ack, reconcile on a separate cadence.
Reconciling only /portfolio/trades. It returns AMM fills in one call (no pagination); CLOB fills live in /portfolio/history (paginated). Cache locally by txHash.
Treating mid-price as fill price. Walk the book one or two levels past your size before sizing.
Forgetting the spread + fee in PnL math. A 7% theoretical edge becomes a 3% realised one round-trip.
Letting REST drift from chain. balanceOf on the outcome token contract is the truth. Reconcile on a cron; alert on any non-dust mismatch.