REST API

The Motoswap REST API serves indexed reads for Ethereum mainnet (chain id 1). Almost every route is a GET. The few writes are wallet-signed (POST /referrals/attribute, the profile routes). Base URL:

https://api.motoswap.org

API host note: api.motoswap.org is the permanent public API host and the only one to build against. It answers for chain id 1. Do not substitute any other hostname you may find: temporary hosts get removed.

Full endpoint reference: reference/api-full-inventory.

Which routes carry data

Deployment status is per contract. The status table is on the contract addresses page, and GET /config is the machine-readable version: a key holds the zero address while its contract is unset for the current phase. Read every address from /config and never integrate against one it did not give you.

Every route answers 200 with its final shape regardless. What differs is whether there is data behind it. GET /config reports the phase as launchPhase. It reads dex with the DEX deployed and open, and it read vamp before the DEX opened.

Every empty answer has the same shape as a populated one, so you can build and test parsers against it.

Responses can carry fields that are not listed here. Ignore fields you do not recognise; do not build a parser that rejects them.

Endpoint groups

A farm position is addressed by chef and pid: GET /pnl/{addr}/farm/{chef}/{pid}. The older /pnl/{addr}/farm/{pid} form answers 404. Take chef from the pool's row in GET /farms.

Pool chart ranges

GET /dex/pools/{pair}/chart takes range, one of 24h, 7d, 30d or 1y, defaulting to 24h. Anything else fails validation. Bucket width follows the range, so a long window stays a bounded response rather than a year of minutes. The width is echoed back as bucketMinutes.

Every range arrives whole. Rows are sparse: a bucket with no trade has no candle.

Candles are OHLC only. minute is a number, the bucket's start in unix minutes, not seconds, so multiply by 60 for a timestamp. Read the spacing off bucketMinutes rather than assuming it.

{
  "bucketMinutes": 1,
  "candles": [
    { "minute": 29828778, "open": "2.4", "high": "2.6", "low": "2.3", "close": "2.5" },
    { "minute": 29828779, "open": "2.5", "high": "2.7", "low": "2.5", "close": "2.6" }
  ]
}

The per-token chart, GET /tokens/{addr}/chart, is a different route with its own frames. These four ranges are the pool chart only.

Non-public routes (do not integrate against)

The backend also mounts operational routes: deep health checks, scheduled jobs, admin controls, an indexer webhook and the web app's own RPC proxy. They are token-gated or rate-limited for the app, and they change without notice. Build only against the routes listed on this page and in the full inventory.

Wire types cheat sheet

• Parse Wei strings with BigInt(value), never Number(value).
• USD 0 is "0", never null. Uncomputable USD (unknown price → 0) is also "0".
• Truly-unknown metric-space fields (priceUsd, aprBps, delta *Pct, decimals) stay null when uncomputable - rendering 0 would mislead. (Exception: /holdings/tokens serves a curated set whose decimals is always known, so that field is non-nullable there.)

Caching / ETag semantics

Cached GETs emit Cache-Control and a weak ETag. Send the tag back verbatim in If-None-Match and expect 304. /config carries Cache-Control but no ETag. /health/live, /version and every write are private, no-store. Tiers:

The header is public, max-age=N, s-maxage=N, stale-while-revalidate=M. Per-user routes key on the wallet's last_activity_block, so polling is free until the user transacts. See guides/caching-and-etags.

Pagination

Cursor lists return `{ items, nextCursor, hasMore }` (/explore/farms names its array farms, /explore/creators names it creators). The cursor is an HMAC-signed token bound to the endpoint

• filters. Cannot be replayed across queries. The per-token and per-pool swap and pool lists take ?page= instead. See guides/cursor-pagination.

Error envelope

Handler errors:

{ "error": "message string" }

A path or query value that fails schema validation (a malformed address, for example) can answer with the validator's own shape instead. Branch on the status code, not the body:

{ "success": false, "error": { "name": "ZodError", "message": "..." } }

4xx and 5xx responses are never cached (middleware overrides Cache-Control to no-store).

CORS

The API's CORS policy is set for the Motoswap app origin. From another origin, a plain GET with no custom headers is readable in a browser, but any request the browser preflights is blocked: the preflight answer carries no Access-Control-Allow-Origin for your origin. That covers a fetch where your script sets If-None-Match, and every JSON POST. Conditional polling with an explicit If-None-Match must run server-side, or rely on the browser's own HTTP cache, which revalidates without a preflight.

Rate limiting

Routes are rate-limited per IP, and under heavy load the backend sheds requests. Both refusals are 429 or 503 carrying Retry-After. Honor the header and back off. In steady state you should never see it - ETag caching keeps polls near zero.