API Reference
These are the actual REST endpoints the aggregator exposes from magma-backend-v2. Every
route group below is registered with the /v1 prefix
(server.register(<p>Routes, { prefix: '/v1' })), so the route file's '/dflow/markets' is served
at /v1/dflow/markets.
Base URL: https://api.magmaprotocol.xyz.
/v1/<platform> ≠ /v1/marketsThe aggregator lives at /v1/<platform> (e.g. /v1/polymarket/markets). MAGMA's native
binary markets live at /v1/markets and are a different product (Solana
magma_binary_vault, with create/resolve/finalize/refund). Do not confuse the two — see
Native binary markets at the bottom and
Binary Markets → Program & API.
All trade/build endpoints return unsigned payloads only; the user signs in the browser (see Trading & Settlement).
DFlow / Kalshi — /v1/dflow/*
Kalshi prediction markets via the DFlow (Pond) execution engine on Solana.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/dflow/markets | Active Kalshi markets/events (cached 30s); category, limit, offset. |
| GET | /v1/dflow/markets/:ticker | Single market detail by ticker. |
| GET | /v1/dflow/markets/:ticker/orderbook | Market orderbook. |
| POST | /v1/dflow/trade | Build a trade via DFlow's /order; returns a base64 unsigned tx (Proof-KYC gated on buys → PROOF_REQUIRED). |
| GET | /v1/dflow/positions/:wallet | Wallet's outcome-token balances (on-chain Token-2022, joined to market metadata). |
| POST | /v1/dflow/redeem | Redeem winning outcome tokens (sell back to settlement). |
| GET | /v1/dflow/order-status?signature= | Poll async CLP fill status to terminal. |
| GET | /v1/dflow/sponsor-status | Is gasless enabled + the sponsor pubkey. |
| POST | /v1/dflow/sponsor-submit | Co-sign a user-signed sponsored tx + broadcast (orderId, signedTransaction). |
Polymarket — /v1/polymarket/*
Polygon CLOB; data via Gamma (discovery) + Data API (positions). Trading is client-side
(@polymarket/clob-client-v2), so there is no backend order/relay route.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/polymarket/markets | Active markets (Gamma, cached 60s); category, limit, offset. |
| GET | /v1/polymarket/markets/search?q= | Keyword search. |
| GET | /v1/polymarket/markets/:conditionId | Single market by condition id. |
| GET | /v1/polymarket/positions/:wallet | Polygon positions (Data API, read-only). |
Limitless — /v1/limitless/*
Base CLOB via the partner SDK; sign-only (backend builds, browser signs, backend relays under HMAC).
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/limitless/markets | Active markets; category, limit, offset. |
| GET | /v1/limitless/markets/search?q= | Keyword search. |
| GET | /v1/limitless/markets/:slug | Single market (slug or address). |
| GET | /v1/limitless/positions/:wallet | Base portfolio positions (public). |
| GET | /v1/limitless/signing-message | Message to sign for partner sub-account registration. |
| POST | /v1/limitless/register | Register the wallet as a partner sub-account (account, signingMessage, signature). |
| GET | /v1/limitless/trade-config/:wallet | Profile id + feeRateBps + hasCreds. |
| POST | /v1/limitless/order/build | Build the unsigned FOK order + EIP-712 typed data. |
| POST | /v1/limitless/order | Relay the signed order under partner HMAC. |
Predict.fun — /v1/predict/*
BNB Chain CLOB via @predictdotfun/sdk; sign-only + one-time referral fee enrolment.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/predict/markets | Active markets, volume-sorted (cached 60s); limit, category, all. |
| GET | /v1/predict/markets/:id | Single market detail. |
| GET | /v1/predict/markets/:id/orderbook | CLOB orderbook. |
| POST | /v1/predict/order/build | Build the unsigned order + EIP-712 typed data (SDK selects exchange via isNegRisk/isYieldBearing). |
| POST | /v1/predict/order | Relay the signed order (x-api-key). |
| GET | /v1/predict/positions/:wallet | Wallet's positions. |
| GET | /v1/predict/trade-config | feeRateBps, hasCreds, hasReferral, testnet, chainId. |
| GET | /v1/predict/auth-message | Message to sign for referral enrolment. |
| POST | /v1/predict/referral | Set MAGMA as the user's referrer (signer, signature, message). |
Rain — /v1/rain/*
Cross-chain AMM; backend returns an unsigned EVM tx for the browser to send. Rain is the only aggregated venue with a create-market route.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/rain/markets | Open AMM markets (cross-chain, cached 60s); category, limit, offset. |
| GET | /v1/rain/markets/search?q= | Search (any language; language optional). |
| GET | /v1/rain/markets/:id | Single market. |
| GET | /v1/rain/positions/:wallet | Wallet's Rain positions. |
| POST | /v1/rain/markets/create | Create a market via Rain (Rain-unique; question ≥ 20 chars, endDate). |
| POST | /v1/rain/trade/quote | Live AMM quote (marketId, outcome, amount). |
| POST | /v1/rain/trade/build | Build the unsigned trade tx (contractAddress + txData); eligibility-gated. |
Opinion — /v1/opinion/*
BNB Chain CLOB for macro / economics markets.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/opinion/markets | Active macro markets (cached 60s); category, limit, offset. |
| GET | /v1/opinion/markets/search?q= | Search. |
| GET | /v1/opinion/markets/:id | Single market. |
| GET | /v1/opinion/markets/:id/orderbook | CLOB orderbook. |
| GET | /v1/opinion/positions/:wallet | Wallet's positions. |
| POST | /v1/opinion/order/build | Build the order (eligibility-gated; returns EIP-712 typed data when the CLOB SDK path is active). |
| POST | /v1/opinion/order/submit | Submit the (optionally signed) order. |
Overtime V2 — /v1/overtime/*
Optimism sports AMM; quote on the backend, bet placed on-chain via SportsAMMV2.trade().
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/overtime/markets | Open sports markets (cached 60s); leagueId, limit, offset. |
| GET | /v1/overtime/live-markets | In-play markets. |
| GET | /v1/overtime/markets/search?q= | Search by team / league. |
| GET | /v1/overtime/markets/:gameId | Single market (with child markets). |
| GET | /v1/overtime/positions/:wallet | Wallet's ticket history. |
| GET | /v1/overtime/config | On-chain contract config (SportsAMMV2, USDC, referrer, chainId). |
| POST | /v1/overtime/quote | Buy-in quote (payout/profit); eligibility-gated. Bet itself is on-chain. |
Conventions
- Prefix: all of the above are under
/v1(registered insrc/server.ts). - Reads are cached (Redis for DFlow/Polymarket/Limitless; in-memory TTL for
Predict/Rain/Opinion/Overtime) and return a
marketsarray with atotal/count(some wrap it insuccess). :wallet/:id/:ticker/:conditionId/:slug/:gameIdare path params keyed to each platform's identifier (see Market Normalization).- Trade endpoints never sign — they build/quote/relay. The signature is produced by the user's wallet in the browser.
Native binary markets (NOT the aggregator)
For contrast — these are MAGMA's own markets, not third-party venues. They share the /v1
prefix but are a separate product served by routes/markets.ts (Solana magma_binary_vault):
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/markets | List native binary markets (filterable). |
| GET | /v1/markets/:id | Single native market. |
| POST | /v1/markets | Create a native binary market (fee-gated). |
| POST | /v1/markets/:id/resolve | Submit oracle resolution. |
| POST | /v1/markets/:id/finalize | Finalize after timelock. |
| POST | /v1/markets/:id/refund | Trigger refund (admin). |
| GET | /v1/markets/:id/positions | Positions for a native market. |
| GET | /v1/markets/user/:wallet | A wallet's native binary positions. |
These are documented in full at Binary Markets → Program & API.
The aggregator never uses /v1/markets.
See also
- Platform Integrations — what each endpoint group backs.
- Trading & Settlement — the build/sign/submit flow.
- Market Normalization — the read endpoints' output shapes.