Myriad API Reference

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

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

• Header: x-api-key: <your_api_key>

• Or Query: ?api_key=<your_api_key>

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

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

• 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

• keyword: search in question title

• min_markets: minimum number of linked markets

• max_markets: maximum number of linked markets

plain text
GET /questions?keyword=politics&page=2&limit=20&min_markets=2&max_markets=10

json
{
  "data": [ /* questions */ ],
  "meta": { "total": 42, "totalMarkets": 130, "page": 1, "limit": 20, "totalPages": 3, "hasNext": true, "hasPrev": false }
}

• id, title, expiresAt

• marketCount: number of linked markets

• markets: array of full market objects (same shape as GET /markets items, including outcomes, oracle, externalSources, etc.)

plain text
GET /questions/1

• id, title, expiresAt

• marketCount: number of linked markets

• markets: array of full market objects (same shape as GET /markets items, including outcomes, oracle, externalSources, etc.)

• page, limit (pagination)

• 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)

• 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.

• 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).

• 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
• 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

• 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

• 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

• 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

• 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 the Order Book API reference

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

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

• 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

• 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

• 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