Myriad API Reference

• Staging - https://api-v2.staging.myriadprotocol.com/

• Production - https://api-v2.myriadprotocol.com/

1. Replace bare-key integrations with HMAC signing (see API key + secret). Keys issued before secrets existed have no secret and cannot be upgraded — mint a new key via POST /auth/api-keys or Myriad Account settings and retire the old one.

2. Connect a wallet to the account by completing one SIWE login (POST /auth/login) with the wallet your orders trade as — API keys minted from that session act on behalf of that wallet.

3. Drop the ?trader= parameter on GET /orders (it must match your connected wallet anyway).

4. Watch for Deprecation/Sunset response headers in the meantime — any request still receiving them will break at the cutover.

plain text
1. GET  /auth/nonce?address=0xYourWallet         → { nonce, message }
2. Sign `message` with the wallet                 # personal_sign — any wallet lib / MetaMask
3. POST /auth/login    { message, signature }     → { accessToken, ... }   # account auto-created
4. POST /auth/api-keys { "label": "my agent" }    → { key, secret }        # Authorization: Bearer <accessToken>

plain text
1. GET  /auth/nonce?address=0xYourWallet           → { nonce, message }
2. Sign `message` with the wallet (personal_sign).
3. POST /auth/login   { message, signature }        → { accessToken, refreshToken, user }
4. Use it:  Authorization: Bearer <accessToken>
5. POST /auth/refresh { refreshToken }  →  new tokens;   POST /auth/logout { refreshToken }

plain text
POST /auth/api-keys      { "label": "MM agent prod" } → { id, key, secret, ... }   # secret shown ONCE
GET  /auth/api-keys                                    # list (never returns secrets)
DELETE /auth/api-keys/:id                              # revoke

javascript
import crypto from 'crypto';
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', SECRET)
  .update(`${ts}.POST./orders.${JSON.stringify(body)}`)
  .digest('hex');
await fetch('https://api-v2.myriadprotocol.com/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': KEY, 'x-api-timestamp': ts, 'x-api-signature': sig },
  body: JSON.stringify(body),
});

• The timestamp must be within ±30s of server time (replay protection).

• path includes the query string; rawBody is the exact bytes sent (empty for GET).

• A legacy bare x-api-key (no signature) is accepted until August 15, 2026, then rejected — see Legacy auth sunset.

plain text
POST /auth/centrifugo/subscription-token   { "channel": "orders:97:0xyourwallet" }  → { token, expiresIn }

• Requests with API key - 200 requests/second per IP and/or API key.

• Requests w/o API key - 30 requests/10 seconds per IP

• Order placement: 200 orders per 10-second window per trader address (shared across single and bulk order endpoints).

• Headers included on responses:
• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

• page (default: 1)

• limit (default: 20, max: 100)

json
{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 123,
    "totalPages": 7,
    "hasNext": true,
    "hasPrev": false
  }
}

• page, limit (pagination)

• trading_model: amm | ob | all (default: amm). AMM-only by default — pass ob for Order Book markets or all for both (see Order Book Concepts)

• sort: volume | volume_24h | volume_notional | volume_notional_24h | liquidity | expires_at | published_at | in_play_starts_at | featured (default: volume)

• order: asc | desc (default: desc)

• network_id: comma-separated list of network ids (e.g. 2741,59144)

• state: open | closed | resolved

• token_address: comma-separated list of ERC20 token addresses

• oracle_address: comma-separated list of oracle contract addresses (matched case-insensitively)

• topics: comma-separated list of topics

• tags: tag slug(s) to filter by. Repeat the param to AND multiple groups; comma-separate within a value to OR (e.g. tags=world-cup&tags=stage-a,stage-b → world-cup AND (stage-a OR stage-b))

• exclude_tags: comma-separated tag slugs to exclude (a market matching ANY is filtered out)

• keyword: full-text search across title, description, and outcome titles

• ids: comma-separated list of on-chain market ids

• event_id: filter to markets belonging to a single event (UUID)

• in_play: boolean (true/false/1/0)

• moneyline: boolean (true/false/1/0)

• min_duration: minimum market duration in seconds (filters by expiresAt - publishedAt)

• max_duration: maximum market duration in seconds (filters by expiresAt - publishedAt)

• in_play_starts_at_gte: unix seconds (inclusive) — only markets with inPlayStartsAt >= this timestamp; markets without inPlayStartsAt are excluded

• in_play_starts_at_lte: unix seconds (inclusive) — only markets with inPlayStartsAt <= this timestamp; markets without inPlayStartsAt are excluded

• group_by_event: boolean (true/false/1/0). When true, sibling markets sharing an event are collapsed into a single event row ({ type: "event", ... }); standalone markets are returned as { type: "market", ...market }. Pagination then operates on logical rows. Event rows for sports carry scoreboard (the match scoreboard, same shape as the market field above) at the event level; child markets in markets[] are ordered canonically (matching outcome0/outcome1), so align them positionally. Filters such as state, keyword, topics, in_play, moneyline, ids, min_duration, max_duration, and the fee filters apply at the sibling level — an event row is included if any of its siblings match; network/token/visibility filters always apply per market.

• Components:
• lp (liquidity provider fee, field fee)
• dt (distributor fee, field distributor_fee)
• tr (treasury fee, field treasury_fee)
• total = fee + treasury_fee + distributor_fee

• Actions: buy, sell

• Operators: lt, lte, gt, gte, eq

• Parameter patterns:
• Component-specific: {action}_{component}_fee_{operator} (e.g., buy_lp_fee_lte=0.01)
• Total: {action}_fee_{operator} (e.g., sell_fee_lt=0.02)

• Examples:
• buy_lp_fee_lte=0.01 → buy LP fee ≤ 1%
• sell_tr_fee_gte=0.0025 → sell treasury fee ≥ 0.25%
• buy_dt_fee_eq=0.003 → buy distributor fee = 0.3%
• sell_fee_lt=0.02 → total sell fee < 2%

• Notes:
• Multiple fee filters are combined with AND.
• All fee values are decimals (e.g., 0.01 = 1%).

plain text
GET /markets?keyword=eth&network_id=2741&page=1&limit=20&sort=volume_24h

• id: blockchain market id

• networkId: number

• slug, title, shortName, ctaName, description

• publishedAt, expiresAt, resolvesAt

• fees, state, voided, resolvedOutcomeId, topics, tags, resolutionSource, resolutionTitle

• token: { address, symbol, name, decimals }

• imageUrl, bannerImageUrl, ogImageUrl

• liquidity, liquidityPrice, volume, volume24h, volumeNotional, volumeNotional24h, users, shares

• featured, featuredAt, inPlay, inPlayStartsAt, perpetual, moneyline

• oracle: always-present object { address, name, url, image_url, data }. address/data are null for markets Myriad resolves itself; name/url/image_url are always populated (brand metadata).

• scoreboard: live-scores scoreboard for standalone sports markets, else null. For event-bound markets the scoreboard lives on the parent event (see GET /events/:id), not the child. Only fields with data are present — a soccer card omits periodScores, a pre-game card omits clock, etc. Always present: type, status, outcome0, outcome1, updatedAt. Shape:
• type: sport slug, e.g. "soccer" / "tennis" — the frontend picks a card layout from this
• status: "scheduled" | "live" | "finished"; statusDetail: provider status text (e.g. "1st Half"), present when known
• startsAt: ISO kickoff time, present when known
• clock: { period?, minute?, stopped } — present only while live and carrying time. Animate the minute locally between refreshes.
• outcome0 / outcome1: the two match sides (always exactly two), each { name, ctaName?, score?, imageUrl? } (optional keys present only when available). outcome0 is the home team / first player; name/ctaName/imageUrl prefer the Myriad market/event data (outcome title, CTA label, outcome image) and fall back to the provider's participant data. Betting outcomes are created in canonical order matching these (home/away or player1/player2), so align rows positionally.
• periodScores: array of { period, outcome0, outcome1 } (e.g. tennis games per set), present only when the sport has them
• venue: { name, location? } — the match venue, present when known
• updatedAt: ISO timestamp of when the score was last captured (score freshness)

• externalSources: array of { id, providerName, externalMarketId, externalMarketUrl, externalMarketTitle } (may be empty)

• topHolders: array (may be empty)

• outcomes: array with:
• id (on-chain outcome id)
• title
• price, closingPrice, priceChange24h
• bestBid, bestAsk: best resting order per side as a 0–1 decimal (binary-implied from the opposite outcome included). null when there is no order on that side, or when the market is not open. Use bestAsk to price a buy without waiting on a separate order-book fetch.
• shares, sharesHeld
• holders
• imageUrl
• tokenId: ERC1155 token id ((ethMarketId << 1) | outcomeId)

• executionMode: 0 (AMM) or 1 (Order Book)

• tradingModel: "amm" or "ob" (string form of executionMode)

• eventId: parent event UUID, or null for standalone markets

• outcomeIndex: index within the parent event, or null

• negRisk: boolean — whether the market belongs to a NegRisk (mutually-exclusive) event

• Numeric monetary/decimal fields are returned as numbers.

• By slug: GET /markets/{slug}

• By id + network: GET /markets/{marketId}?network_id=2741

• Field outcomes[*].price_charts.

• Timeframes and buckets
• 24h: 5-minute (max 288)
• 7d: 30-minute (max 336)
• 30d: 4-hour (max 180)
• all: 4-hour

• Series end at min(now, expiresAt) with backfill from the last known price before the window start.

plain text
GET /markets/164?network_id=2741

• By slug: GET /markets/{slug}/events

• By id + network: GET /markets/{marketId}/events?network_id=2741

• page, limit

• trading_model: amm | ob | all (default amm) — pass ob or all to include Order Book market events

• since: unix seconds (inclusive)

• until: unix seconds (inclusive)

• only_relevant: 1/true/yes to exclude wash-trade actions (where relevant = false)

• user: wallet address

• action: buy | sell | add_liquidity | remove_liquidity | claim_winnings | claim_liquidity | claim_fees | claim_voided

• marketTitle, marketSlug, marketId, networkId

• outcomeTitle, outcomeId

• imageUrl

• shares, value: numbers

• timestamp: unix seconds

• blockNumber: number

• token: ERC20 token address used for this market

• txId: transaction hash

plain text
GET /markets/164/events?network_id=2741&since=1755600000&until=1755800000&page=1&limit=50

• By slug: GET /markets/{slug}/referrals

• By id + network: GET /markets/{marketId}/referrals?network_id=2741

• page, limit

• since: unix seconds (optional, inclusive)

• until: unix seconds (optional, inclusive)

• code: referral code (optional)

• user: wallet address

• action: buy | sell (referral trade type)

• marketTitle, marketSlug, marketId, networkId

• outcomeTitle, outcomeId

• imageUrl

• value: number (trade value that generated referral fees)

• timestamp: unix seconds

• blockNumber: number

• token: ERC20 token address used for this market

• code: referral code used

• fees:
• lp (number): LP fee portion attributed to this referral
• treasury (number): treasury fee portion
• distributor (number): distributor/referrer fee portion

plain text
GET /markets/164/referrals?network_id=2741&since=1755600000&until=1755800000&page=1&limit=50

• By slug: GET /markets/{slug}/holders

• By id + network: GET /markets/{marketId}/holders?network_id=2741

• page, limit (pagination; limit applies per outcome)

• network_id (required when using marketId)

• outcomeId: number

• outcomeTitle: string | null

• totalHolders: total addresses with ≥ 1 share in this outcome

• holders: array limited per outcome with:
• user: address
• shares: number

• total equals the maximum total_holders across outcomes for this market.

• totalPages = ceil(max(total_holders) / limit); limit is applied per outcome.

plain text
GET /markets/164/holders?network_id=2741&page=1&limit=50

json
{
  "bids": [
    ["500000000000000000", "3000000000000000000"],
    ["490000000000000000", "1500000000000000000"]
  ],
  "asks": [
    ["510000000000000000", "2000000000000000000"],
    ["520000000000000000", "5000000000000000000"]
  ]
}

json
[
  {
    "price": "0.5",
    "priceAfterFees": "0.51",
    "amount": "1000000000000000000",
    "side": "buy",
    "outcome": 0,
    "txHash": "0x...",
    "timestamp": 1719835200,
    "fees": {
      "total": "10000000000000000",
      "lp": "0",
      "treasury": "5000000000000000",
      "distributor": "5000000000000000"
    }
  }
]

• Method: POST

• Path: /markets/quote

• Body: JSON

• Exactly one of the following is required (send only one):
• market_id (number): on-chain market id + network_id (number): network id
• market_slug (string)

• outcome_id (number, required): on-chain outcome id

• action (string, required): buy | sell

• Exactly one of the following is required (send only one):
• value (number): amount of tokens to spend (buy) or receive (sell)
• shares (number): number of shares to buy or sell

• slippage (number, optional, default 0.005): between 0 (0%) and 1 (100%)

• For buy: provide only value; shares must be omitted.

• For sell: provide exactly one of value or shares.

• Market must exist and be open.

• Market must have at least 2 outcomes and sufficient shares/liquidity.

• value (number): input value used for the calculation

• shares (number): expected shares bought/sold

• shares_threshold (number): min acceptable based on slippage (for buy, min shares; for sell, min value)

• price_average (number): average execution price

• price_before (number): price before the trade

• price_after (number): price after the trade

• calldata (string): hex-encoded calldata for the contract

• net_amount (number): value after protocol/treasury/distributor fees

• fees:
• treasury (number)
• distributor (number)
• fee (number)

json
{
  "market_id": 164,
  "outcome_id": 0,
  "network_id": 2741,
  "action": "buy",
  "value": 100,
  "slippage": 0.01
}

json
{
  "value": 100,
  "shares": 312.3456,
  "shares_threshold": 309.2221,
  "price_average": 0.3201,
  "price_before": 0.315,
  "price_after": 0.3252,
  "calldata": "0x...",
  "net_amount": 99.3,
  "fees": {
    "treasury": 0.2,
    "distributor": 0.1,
    "fee": 0.4
  }
}

• 400 Invalid request parameters, unsupported network, market not open, insufficient liquidity, or invalid slippage/value/shares combination

• 404 Market or outcome not found

• 500 Unable to resolve token decimals or unexpected server error

1. (Optionally) approve ERC20 collateral spending for the PredictionMarket contract (buy-only, included only when allowance is insufficient)

2. Transfer a frontend fee to to_wallet

3. Execute the trade

• All fields from POST /markets/quote

• fee (number, required): decimal fee rate, between 0 and 0.05 (e.g. 0.01 = 1%)

• from_wallet (string, required): wallet that will sign/send the bundle (used for allowance+balance checks)

• to_wallet (string, required): fee recipient wallet

• All fields from POST /markets/quote

• fees.frontend (number): frontend fee amount in token units

• approval:
• required (boolean)
• currentAllowanceWei (string, optional)
• requiredAllowanceWei (string, optional)

• calldata (object): ready to pass to wallet_sendCalls as the first (and only) params item to an EIP-5792 capable wallet
• version: "2.0.0"
• from: sender address (same as from_wallet)
• chainId: hex chain id (derived from market network_id)
• atomicRequired: true
• calls: ordered array of { to, data, value } (hex quantities)

json
{
  "market_id": 164,
  "outcome_id": 0,
  "network_id": 2741,
  "action": "buy",
  "value": 100,
  "slippage": 0.01,
  "fee": 0.01,
  "from_wallet": "0x0000000000000000000000000000000000000001",
  "to_wallet": "0x0000000000000000000000000000000000000002"
}

json
{
    "value": 100,
    "shares": 107.71301097629218,
    "shares_threshold": 107.17444592141072,
    "price_average": 0.9191090203744288,
    "price_before": 0.89954079,
    "price_after": 0.9019004096700267,
    "calldata": {
        "version": "2.0.0",
        "from": "0x0000000000000000000000000000000000000001",
        "chainId": "0xab5",
        "atomicRequired": true,
        "calls": [
            {
                "to": "0x55d398326f99059fF775485246999027B3197955",
                "data": "0x095ea7b300000000000000000000000039e66ee6b2ddaf4defded3038e0162180dbef3400000000000000000000000000000000000000000000000055de6a779bbac0000",
                "value": "0x0"
            },
            {
                "to": "0x55d398326f99059fF775485246999027B3197955",
                "data": "0xa9059cbb00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000de0b6b3a7640000",
                "value": "0x0"
            },
            {
                "to": "0x39E66eE6b2ddaf4DEfDEd3038E0162180dbeF340",
                "data": "0x1281311d00000000000000000000000000000000000000000000000000000000000023270000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000005cf581ebb20ffaa2d0000000000000000000000000000000000000000000000055de6a779bbac0000",
                "value": "0x0"
            }
        ]
    },
    "net_amount": 97.02,
    "fees": {
        "treasury": 0,
        "distributor": 0.99,
        "fee": 0.99,
        "frontend": 1
    },
    "approval": {
        "required": true,
        "currentAllowanceWei": "0",
        "requiredAllowanceWei": "99000000000000000000"
    }
}

• MetaMask

• ThirdWeb

• Buy fee semantics: for action="buy", the request value is treated as the total amount charged from the user. The frontend fee is deducted first, and the trade is quoted/executed with the remaining amount. The response value equals the total charged (same as request value).

• Sell fee semantics: for action="sell", the frontend fee is charged after the trade, and the response value reflects the amount after frontend fee deduction.

• Clients should strongly prefer requiring atomic bundling (i.e. "atomicRequired": true) so the fee transfer is not executed without the trade.

• Insufficient balance (buy only): for action="buy", the from_wallet balance is checked against the total spend (trade value + frontend fee). If it can't cover the total, the endpoint returns 400 with the token, current balance, and required amount (in wei).

• 400 Invalid request parameters; fee too high for the provided value; insufficient from_wallet balance (buy); plus any POST /markets/quote error

• 401 Missing/invalid API key (no authenticated user)

• 403 API key is not whitelisted for frontend fees

• 404 Market or outcome not found

• 500 Unable to resolve token decimals or unexpected server error

• Method: POST

• Path: /markets/claim

• Body: JSON

• Exactly one of the following is required (send only one):
• market_id (number): on-chain market id + network_id (number): network id
• market_slug (string)

• outcome_id (number, optional): on-chain outcome id (only required when market is voided)

• Market must exist and be resolved.

• action (string): claim_winnings | claim_voided, depending on whether the market is voided (both require the market to be resolved)

• outcome_id: winning outcome id, or voided outcome id to be claimed

• calldata (string): hex-encoded calldata for the contract

json
{
  "market_id": 164,
  "outcome_id": 0,
  "network_id": 2741
}

json
{
  "action": "claim_winnings",
  "outcome_id": 0,
  "calldata": "0x..."
}

• 400 Invalid request parameters, unsupported network, market not resolved

• 404 Market or outcome not found

• 500 Unable to resolve token decimals or unexpected server error

• page, limit

• trading_model: amm | ob | all (default amm) — pass ob to filter to Order Book actions only

• market_id: chain market id (optional)

• market_slug: market slug (optional; resolves to id/network for filtering)

• network_id: number (optional)

• token_address: comma-separated list of ERC20 token addresses (optional)

• since: unix seconds (inclusive)

• until: unix seconds (inclusive)

• only_relevant: 1/true/yes to exclude wash-trade actions (optional)

• user: wallet address

• action: action type

• marketTitle, marketSlug, marketId, networkId

• outcomeTitle, outcomeId

• imageUrl

• shares, value: numbers

• timestamp: unix seconds

• blockNumber: number

• token: ERC20 token address

• txId: transaction hash

plain text
GET /users/0x1234.../events?network_id=2741&market_id=144&page=1&limit=50

• page, limit

• market_id: chain market id (optional)

• market_slug: market slug (optional; resolves to id/network)

• network_id: number (optional)

• since: unix seconds (optional, inclusive)

• until: unix seconds (optional, inclusive)

• code: referral code (optional)

• user: wallet address (referrer or user recorded on referral)

• action: buy | sell

• marketTitle, marketSlug, marketId, networkId

• outcomeTitle, outcomeId

• imageUrl

• value: number

• timestamp: unix seconds

• blockNumber: number

• token: ERC20 token address

• code: referral code used

• fees:
• lp (number)
• treasury (number)
• distributor (number)

plain text
GET /users/0x1234.../referrals?network_id=2741&market_id=144&page=1&limit=50

• page, limit

• trading_model: amm | ob | all (default amm) — pass ob for Order Book positions or all for both

• min_shares: minimum shares threshold per outcome and for liquidity positions (default 0.1)

• market_slug: market unique slug (optional)

• market_id: chain market id (optional)

• network_id: number (optional)

• token_address: comma-separated list of ERC20 token addresses (optional)

• status: comma-separated subset of ongoing | lost | won | claimed | sold | voided, or all to include every position regardless of size (optional)

• exclude_history: true to return only currently-actionable positions (open, or resolved+unclaimed) (optional)

• keyword: full-text search across title, description, and outcome titles (optional)

• sort: asc | desc (default desc)

• sort_by: created_at (default) | profit | roi | shares | value | marketTitle | expires_at

• group_by_event: true/1 to fold positions sharing an event into a single event row (optional)

• Positions with net shares < min_shares (default 0.1) are excluded (unless status is provided or status=all).

• Pagination and totals are computed after filtering.

• price is the current outcome price; shares is net buys minus sells; average buy price follows proportional cost-basis when selling.

• marketId, marketTitle, marketSlug, outcomeId, outcomeTitle, networkId, token, imageUrl

• shares: net shares held (number)

• price: average buy price (number)

• value: shares * currentPrice

• profit: shares * (currentPrice - price)

• roi: (profit - totalAmount) / totalAmount (null if not computable)

• totalProfit, totalRoi: realized + unrealized P/L over the lifetime of the position (null if not computable)

• positionFees, totalFees: fees attributed to the open position / to all activity on it

• winningsToClaim: true if resolved, holding winning outcome, and no claim_winnings

• winningsClaimed: true if resolved, holding winning outcome, and claim_winnings exists

• voidedWinningsToClaim, voidedWinningsClaimed: same, for voided markets

• claimed: true if winnings or voided winnings were claimed

• status: ongoing | lost | won | claimed | sold | voided

• expiresAt: market expiry (ISO string or null)

• eventId: parent event UUID, or null

• executionMode: 0 (AMM) or 1 (Order Book); tokenId (ERC1155 id) is set for Order Book positions — see Order Book Concepts

plain text
GET /users/0x1234.../portfolio?network_id=2741&token_address=0x84A71ccD554Cc1b02749b35d22F684CC8ec987e1&page=1&limit=20

• page, limit (pagination; default limit=10, max 100)

• trading_model: amm | ob | all (default amm) — pass ob for Order Book positions or all for both

• min_shares: minimum shares threshold per outcome and for liquidity positions (default 0.1)

• network_id: number (optional)

• state: open | closed | resolved (optional)

• token_address: ERC20 token address (optional)

• topics: comma-separated list of topics (optional)

• keyword: full-text search across title, description, and outcome titles

• market_ids: comma-separated list of {networkId}:{marketId} pairs (optional), e.g. 2741:164,2741:200

• market_slug: comma-separated market slug(s) (optional)

• status: comma-separated subset of ongoing | lost | won | claimed | sold | voided, or all (optional)

• sort: asc | desc (default desc); sort_by: created_at (default)

• group_by_event: true/1 to fold sibling markets into a single event row (optional)

• Buy fee filters (optional; decimals between 0 and 1):
• buy_lp_fee_lt, buy_lp_fee_lte, buy_lp_fee_gt, buy_lp_fee_gte, buy_lp_fee_eq

• market: a market object (same shape as /markets items)

• portfolio:
• positions: array of outcome positions with:
• marketId, marketTitle, marketSlug, imageUrl, networkId, token
• outcomeId, outcomeTitle
• shares, price, value, profit, roi, totalProfit, totalRoi, positionFees, totalFees
• winningsToClaim, winningsClaimed, voidedWinningsToClaim, voidedWinningsClaimed, claimed
• status: ongoing | lost | won | claimed | sold | voided
• liquidity:
• shares, price, value
• totalAdded, totalRemoved, totalClaimed, totalToClaim
• feesClaimed

json
{
  "name": "MyriadCTFExchange",
  "version": "1",
  "chainId": "<chain_id>",
  "verifyingContract": "<exchange_contract_address>"
}

plain text
Order(
  address trader,
  uint256 marketId,
  uint8   outcomeId,
  uint8   side,
  uint256 amount,
  uint256 price,
  uint256 minFillAmount,
  uint256 nonce,
  uint256 expiration
)

• Price: integer in [1, 1e18] representing a fraction of 1 collateral token per share. 0.50 = 500000000000000000.

• Amount: integer in the token's smallest unit (e.g. for 18-decimal tokens, 1e18 = 1 share).

• ✅ Valid: 10000000000000000 (0.01), 570000000000000000 (0.57), 990000000000000000 (0.99), 1000000000000000000 (1.00).

• ❌ Rejected: 575000000000000000 (0.575 — finer than a cent), 569999999999999936 (a floating-point artifact for 0.57), 1 (1 wei).

plain text
 Trader                         API                           Matcher (on-chain)
   |                             |                                   |
   |  POST /orders (signed)      |                                   |
   | --------------------------► |                                   |
   |                             |  validate, verify sig,            |
   |                             |  check balance/allowance          |
   |                             |  insert into orders table         |
   |  ◄─ { orderHash, status }   |                                   |
   |                             |  NOTIFY orders_changed            |
   |                             | ────────────────────────────────► |
   |                             |                                   |  load open orders
   |                             |                                   |  find matches
   |                             |                                   |  call exchange contract
   |                             |                                   |  (matchMultipleOrdersWithFees
   |                             |                                   |   or matchCrossMarketOrders)
   |                             |  ◄──── OrdersMatched event ────── |
   |                             |  update orders + actions          |
   |                             |                                   |
   |  GET /orders/:hash          |                                   |
   | --------------------------► |                                   |
   |  ◄─ { status: "filled" }    |                                   |

1. Place order — trader signs an EIP-712 order and sends it to POST /orders.

2. Validation — the API verifies the signature, checks on-chain balance/allowance, and stores the order.

3. Matching — the matcher service loads open orders, finds compatible pairs/sets, and calls the exchange contract.

4. Settlement — the exchange contract atomically transfers shares and collateral on-chain.

5. Sync — the API listens for OrdersMatched / OrderCancelled events and updates order statuses.

json
{
  "order": {
    "trader": "0x1234...abcd",
    "marketId": "42",
    "outcomeId": 0,
    "side": 0,
    "amount": "1000000000000000000",
    "price": "500000000000000000",
    "minFillAmount": "0",
    "nonce": "1",
    "expiration": "0"
  },
  "signature": "0x<130 hex chars>",
  "signatureType": 0,
  "network_id": 56,
  "time_in_force": "GTC",
  "accept_by": "0",
  "client_order_id": "17256719159"
}

• price must be on the 0.01 tick grid (a multiple of 1e16); an off-tick price is rejected with 400 (see Price Tick Size).

• GTC orders must have expiration = 0.

• GTD orders must have expiration > 0.

• PO orders accept any expiration — 0 behaves GTC-style, >0 behaves GTD-style.

• accept_by, when non-zero, must not already be in the past — a submission whose receive window has already passed is rejected with 400 (the order is not placed).

• For buy orders (non-PO/FOK/FAK): the trader must have sufficient collateral balance and allowance on the exchange contract for notional + fee (where notional = amount * price / 1e18). For NegRisk markets the check is performed against the underlying collateral token (the network's configured collateral), not a wrapped collateral — so traders only need to approve the underlying token.

• For sell orders (non-PO/FOK/FAK): the trader must hold enough outcome shares in the ConditionalTokens contract and have approved the exchange via setApprovalForAll.

• Reserved funds: the balance check subtracts obligations already parked in the trader's open orders on the same market (buys reserve (amount - filled) * price / 1e18 of collateral; sells reserve unfilled shares per outcome). A new order must fit within balance - reserved. To replace an existing order without cancelling it first, pass its hash as replaces_order_hash so it is left out of the reservation.

• FOK, FAK, and PO skip the upfront collateral check — the on-chain matchOrders* call enforces allowance/balance at fill time.

json
{
  "orderHash": "0x...",
  "status": "open",
  "timeInForce": "GTC",
  "clientOrderId": "1ccd-17256719159"
}

json
{
  "data": [
    {
      "orderHash": "0x...",
      "clientOrderId": "1ccd-17256719159",
      "order": {
        "trader": "0x...",
        "marketId": 42,
        "outcomeId": 0,
        "side": 0,
        "amount": "1000000000000000000",
        "price": "500000000000000000",
        "minFillAmount": "0",
        "nonce": "1",
        "expiration": "0"
      },
      "status": "open",
      "signatureType": 0,
      "filledAmount": "0",
      "timeInForce": "GTC",
      "createdAt": "2025-07-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5000,
    "total": 137,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

json
{
  "orderHash": "0x...",
  "clientOrderId": "1ccd-17256719159",
  "order": {
    "trader": "0x...",
    "marketId": 42,
    "outcomeId": 0,
    "side": 0,
    "amount": "1000000000000000000",
    "price": "500000000000000000",
    "minFillAmount": "0",
    "nonce": "1",
    "expiration": "0"
  },
  "status": "open",
  "signatureType": 0,
  "filledAmount": "0",
  "timeInForce": "GTC",
  "networkId": 56,
  "createdAt": "2025-07-01T12:00:00.000Z",
  "updatedAt": "2025-07-01T12:00:00.000Z",
  "cancelledAt": null,
  "filledAt": null
}

• an order hash — 0x + 64 hex chars; or

• a raw client_order_id — the value you passed to POST /orders (e.g. 17256719159), without the user prefix. The server reconstructs the namespaced id from the authenticated user, so cancelling by client_order_id requires an API key (x-api-key). The signed order in the body must still match the stored order.

json
{
  "order": {
    "trader": "0x...",
    "marketId": "42",
    "outcomeId": 0,
    "side": 0,
    "amount": "1000000000000000000",
    "price": "500000000000000000",
    "minFillAmount": "0",
    "nonce": "1",
    "expiration": "0"
  },
  "signature": "0x<130 hex chars>",
  "signatureType": 0,
  "network_id": 56
}

json
{
  "orderHash": "0x...",
  "status": "cancelled"
}

json
{
  "orders": [
    {
      "order": { "trader": "0x...", "marketId": "42", "outcomeId": 0, "side": 0, "amount": "1000000000000000000", "price": "500000000000000000", "minFillAmount": "0", "nonce": "1", "expiration": "0" },
      "signature": "0x<130 hex chars>",
      "time_in_force": "GTC"
    }
  ],
  "network_id": 56,
  "allow_partial": true
}

json
{
  "placed": ["0xabc...", "0xdef..."],
  "errors": [
    { "index": 3, "orderHash": null, "reason": "Invalid order signature" }
  ]
}

json
{
  "cancel": [
    { "order": { /* ... */ }, "signature": "0x..." }
  ],
  "place": [
    { "order": { /* ... */ }, "signature": "0x...", "time_in_force": "GTC" }
  ],
  "network_id": 56,
  "allow_partial": true
}

json
{
  "placed": ["0xabc..."],
  "cancelled": ["0xdef..."],
  "errors": [
    { "phase": "place", "index": 2, "orderHash": null, "reason": "Market not found" }
  ]
}

json
{
  "orders": [
    {
      "order": {
        "trader": "0x...",
        "marketId": "42",
        "outcomeId": 0,
        "side": 0,
        "amount": "1000000000000000000",
        "price": "500000000000000000",
        "minFillAmount": "0",
        "nonce": "1",
        "expiration": "0"
      },
      "signature": "0x<130 hex chars>"
    }
  ],
  "network_id": 56,
  "allow_partial": true
}

json
{
  "cancelled": ["0xabc...", "0xdef..."],
  "errors": [
    { "index": 2, "orderHash": "0x123...", "reason": "Order not found" }
  ]
}

plain text
CancelAll(
  address trader,
  uint256 marketId,
  uint256 timestamp
)

json
{
  "trader": "0x1234...abcd",
  "market_id": 42,
  "timestamp": "1719835200",
  "signature": "0x<130 hex chars>",
  "signatureType": 0,
  "network_id": 56
}

json
{
  "cancelled_count": 12,
  "market_ids_affected": ["uuid-...", "uuid-..."]
}

json
{
  "market_id": 42,
  "amount": "1000000000000000000",
  "network_id": 56
}

json
{
  "to": "0x<ConditionalTokens address>",
  "calldata": "0x...",
  "value": "0"
}

json
{
  "market_id": 42,
  "network_id": 56
}

json
{
  "event_id": "0x<64 hex chars>",
  "outcome_index": 0,
  "amount": "1000000000000000000",
  "network_id": 56
}

• NegRisk events (negRisk: true) — sibling markets are mutually exclusive: exactly one resolves to Yes and all others resolve to No (e.g. "Who will win the election?").

• Non-NegRisk events (negRisk: false) — sibling markets resolve independently, so zero, one, or multiple siblings can resolve to Yes (e.g. "Which teams will make the playoffs?").

• type: "event" — discriminator (matches the shape produced by grouped endpoints elsewhere).

• negRisk / negRiskId — replaces the previous ethEventId field. negRiskId is the on-chain NegRisk event id (bytes32 hex).

• Aggregated trading metrics (volume, volume24h, volumeNotional, volumeNotional24h, liquidity, users, featured, featuredAt) summed/aggregated across the event's sibling markets.

• markets — array of fully-serialized sibling markets (same shape as GET /markets items, including their own outcomes and externalSources), ordered by outcomeIndex.

• scoreboard — for sports events, the live-scores scoreboard (same object documented for GET /markets items); omitted for non-sports events. Sibling markets are in canonical outcome order, so align their rows positionally with the scoreboard's outcome0/outcome1.

• externalSources — event-level external sources.

json
{
  "data": [
    {
      "type": "event",
      "id": "uuid-...",
      "networkId": 56,
      "slug": "2028-election",
      "title": "Who will win the 2028 election?",
      "description": "...",
      "imageUrl": "https://...",
      "bannerImageUrl": "https://...",
      "state": "open",
      "resolvedOutcomeIndex": null,
      "expiresAt": "2028-11-05T00:00:00.000Z",
      "publishedAt": "2025-06-01T00:00:00.000Z",
      "negRisk": true,
      "negRiskId": "0x...",
      "volume": 123456.78,
      "volume24h": 1234.56,
      "volumeNotional": 234567.89,
      "volumeNotional24h": 2345.67,
      "liquidity": 9876.54,
      "users": 1234,
      "featured": false,
      "featuredAt": null,
      "externalSources": [],
      "markets": [
        {
          "id": 42,
          "title": "Candidate A",
          "outcomeIndex": 0,
          "state": "open",
          "outcomes": [ /* ... */ ],
          "externalSources": [ /* ... */ ]
          /* ...full market shape... */
        }
      ]
    }
  ]
}

json
{
  "outcomes": [
    {
      "marketId": "uuid-...",
      "ethMarketId": 42,
      "outcomeIndex": 0,
      "title": "Candidate A",
      "tokenId": "84",
      "orderbook": {
        "bids": [["500000000000000000", "1000000000000000000"]],
        "asks": [["520000000000000000", "2000000000000000000"]]
      }
    },
    {
      "marketId": "uuid-...",
      "ethMarketId": 43,
      "outcomeIndex": 1,
      "title": "Candidate B",
      "tokenId": "86",
      "orderbook": {
        "bids": [],
        "asks": []
      }
    }
  ]
}

json
{
  "data": [
    {
      "user": "0x...",
      "action": "buy",
      "marketTitle": "Candidate A",
      "marketSlug": "candidate-a",
      "marketId": 42,
      "networkId": 56,
      "outcomeTitle": "Yes",
      "outcomeId": 0,
      "imageUrl": "https://...",
      "shares": 1.5,
      "value": 0.75,
      "timestamp": 1719835200,
      "blockNumber": 12345678,
      "token": "0x<collateral address>",
      "txId": "0x..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7,
    "hasNext": true,
    "hasPrev": false
  }
}

javascript
import { Centrifuge } from 'centrifuge';

const client = new Centrifuge('wss://ws.myriadprotocol.com/ws');

const sub = client.newSubscription('orderbook:56:42');
sub.on('publication', (ctx) => console.log(ctx.data));
sub.subscribe();

client.connect();

1. Connect — after the socket opens, send a connect command. Anonymous connections send empty params: { "connect": {}, "id": 1 }.

2. Subscribe — once the connect reply arrives, send one subscribe command per channel: { "subscribe": { "channel": "…" }, "id": N }. Each command needs a unique incrementing id.

3. Ping/pong — the server periodically sends an empty frame ({}); reply with an empty frame ({}) to keep the connection alive.

4. Publications — channel data arrives as an async push with no id: { "push": { "channel": "…", "pub": { "data": { … } } } }. The payload you care about is push.pub.data.

javascript
import WebSocket from 'ws';

const ws = new WebSocket('wss://ws.myriadprotocol.com/ws');
const channels = ['orderbook:56:42', 'trades:56:42'];
let nextId = 1;

const send = (cmd) => ws.send(JSON.stringify(cmd));

ws.on('open', () => send({ connect: {}, id: nextId++ })); // 1. authenticate (anonymous)

ws.on('message', (frame) => {
  for (const line of frame.toString().split('\n')) {
    if (!line) continue;
    const msg = JSON.parse(line);

    if (Object.keys(msg).length === 0) { send({}); continue; }          // 3. ping → pong

    if (msg.connect) {                                                  // 2. connect reply → subscribe
      for (const channel of channels) send({ subscribe: { channel }, id: nextId++ });
      continue;
    }

    if (msg.push?.pub) {                                                // 4. channel data
      console.log(msg.push.channel, msg.push.pub.data);
    }
  }
});

javascript
client.newSubscription('trades:56:42', { positioned: true, recoverable: true });

• Each Centrifugo publication carries the JSON object documented below as its data.

• All numeric fields are decimal strings. Prices are 1e18-scaled (see Price and Amount Scale); amounts/shares and fees are in the token's smallest unit.

• ts is a unix timestamp in milliseconds.

• Server-side, publishes are coalesced into ~100 ms windows, so a single message may batch several changes.

json
{
  "marketId": 42,
  "networkId": 56,
  "ts": 1719835200123,
  "changes": [
    { "outcome": 0, "side": "bid", "price": "500000000000000000", "amount": "3000000000000000000" },
    { "outcome": 0, "side": "ask", "price": "510000000000000000", "amount": "0" }
  ]
}

json
{
  "marketId": 42,
  "networkId": 56,
  "txHash": "0x...",
  "blockNumber": 12345678,
  "ts": 1719835200123,
  "taker": {
    "trader": "0x...",
    "outcome": 0,
    "side": "buy",
    "orderHash": "0x...",
    "totalAmount": "1000000000000000000",
    "averagePrice": "500000000000000000",
    "averagePriceAfterFees": "510000000000000000",
    "totalFees": { "total": "10000000000000000", "lp": "0", "treasury": "5000000000000000", "distributor": "5000000000000000" }
  },
  "makers": [
    {
      "trader": "0x...",
      "role": "maker",
      "outcome": 0,
      "side": "sell",
      "orderHash": "0x...",
      "price": "500000000000000000",
      "priceAfterFees": "500000000000000000",
      "amount": "1000000000000000000",
      "fees": { "total": "0", "lp": "0", "treasury": "0", "distributor": "0" }
    }
  ]
}

json
{
  "networkId": 56,
  "marketId": 42,
  "txHash": "0x...",
  "matchType": "direct",
  "status": "submitted",
  "ts": 1719835200123,
  "legs": [
    { "trader": "0x...", "role": "taker", "orderHash": "0x...", "outcome": 0, "side": "buy", "fillAmount": "1000000000000000000" },
    { "trader": "0x...", "role": "maker", "orderHash": "0x...", "outcome": 0, "side": "sell", "fillAmount": "1000000000000000000" }
  ]
}

json
{
  "networkId": 56,
  "marketId": 42,
  "ts": 1719835200123,
  "outcomes": [
    { "outcome": 0, "bestBid": "500000000000000000", "bestAsk": "510000000000000000", "last": "505000000000000000" },
    { "outcome": 1, "bestBid": "490000000000000000", "bestAsk": "500000000000000000" }
  ]
}

json
{
  "type": "PARTIALLY_FILLED",
  "orderHash": "0x...",
  "networkId": 56,
  "marketId": 42,
  "trader": "0x...",
  "side": "buy",
  "outcome": 0,
  "price": "500000000000000000",
  "amount": "1000000000000000000",
  "filledAmount": "400000000000000000",
  "status": "open",
  "timeInForce": "GTC",
  "matchTxHash": "0x...",
  "createdAt": "2025-07-01T12:00:00.000Z",
  "updatedAt": "2025-07-01T12:00:05.000Z"
}

json
{
  "networkId": 56,
  "marketId": 42,
  "trader": "0x...",
  "outcome": 0,
  "delta": "+1000000000000000000",
  "balance": "3000000000000000000",
  "averageEntryPrice": "500000000000000000",
  "reason": "fill",
  "txHash": "0x...",
  "ts": 1719835200123
}

json
{
  "type": "resolved",
  "networkId": 56,
  "marketId": 42
}

• type: filter to a single tag namespace (e.g. type=league)

plain text
GET /tags?type=league

json
{
  "data": [
    { "marketCount": 18, "tag": { "type": "league", "title": "Premier League", "slug": "premier-league", "imageUrl": "https://..." } }
  ]
}

• network_id: comma-separated list of network ids

plain text
GET /topics?network_id=2741,59144

json
{
  "data": [
    { "topic": "crypto", "marketCount": 42 },
    { "topic": "sports", "marketCount": 31 }
  ]
}

• Historical price data is built from on-chain events (MarketOutcomeShares) and stored in prices.

• Outcome prices are derived from outcome shares.

• Liquidity price computation follows the contract logic; resolved markets use final shares/liquidity, otherwise #outcomes / (liquidity * Σ(1/shares)).

• 401 Unauthorized – missing/invalid API key

• 429 Too Many Requests – rate limit exceeded

• 400 Bad Request – invalid query parameters

• 404 Not Found – resource not found

• 409 Conflict – duplicate order (Order Book: duplicate hash or client_order_id)

• 500 Internal Server Error

1. Global report: https://drive.google.com/file/d/1RNqS5NrVL9sCCPhdPKU6iWdyftFyHVYg/view

2. Reports per component and reviews:
1. https://github.com/Cyfrin/cyfrin-audit-reports/blob/main/reports/2026-03-13-cyfrin-myriad-clob-v2.0.pdf
2. https://github.com/Cyfrin/cyfrin-audit-reports/blob/main/reports/2026-04-08-cyfrin-myriad-realitio-oracle-v2.0.pdf
3. https://github.com/Cyfrin/cyfrin-audit-reports/blob/main/reports/2026-04-07-cyfrin-myriad-pr145-v2.0.pdf

• Added API key authentication

• Added rate limiting

• Markets endpoints with keyword search and charts

• Market events and user events endpoints with timestamp filtering

• Historical prices ingestion + charting

• Added portfolio endpoint

• Added market holders endpoint

• Added market quote endpoint

• Added market quote_with_fee endpoint

• Made most API endpoints public