# API Reference **Base URLs:** | Environment | Base URL | API key prefix | | ----------- | --------------------------------- | ------------------ | | Production | `https://api.dimes.fi/v1` | `dm_live_skey_...` | | Sandbox | `https://api-sandbox.dimes.fi/v1` | `dm_sbx_skey_...` | Pick one environment per integration. Keys and URLs are not interchangeable across environments — see [Environments](/for-developers/environments.md) for the full comparison. **OpenAPI spec:** * Interactive Swagger UI: [`https://api.dimes.fi/v1/customer-docs`](https://api.dimes.fi/v1/customer-docs) (production) or [`https://api-sandbox.dimes.fi/v1/customer-docs`](https://api-sandbox.dimes.fi/v1/customer-docs) (sandbox) * Raw JSON: [`https://api.dimes.fi/v1/customer-docs-json`](https://api.dimes.fi/v1/customer-docs-json) (production) or [`https://api-sandbox.dimes.fi/v1/customer-docs-json`](https://api-sandbox.dimes.fi/v1/customer-docs-json) (sandbox) *** ## Conventions | Convention | Choice | | ------------------- | -------------------------------------------------- | | **Field casing** | `snake_case` | | **URL path casing** | `kebab-case` | | **Pagination** | Cursor-based | | **List envelope** | `{ "data": [...], "has_more": bool }` | | **Error format** | `{ "error": { "type", "code", "message" } }` | | **Monetary values** | Pips (string) + dollar (string) | | **IDs** | Prefixed strings (`dm_pos_`, `dm_off_`, `dm_mkt_`) | ### Monetary values Every monetary field appears twice — as precise internal units (pips, string) and as a human-readable dollar amount ( string): ```json { "entry_price_usd_pips": "6500", "entry_price_usd": "0.65", "collateral_usd_pips": "500000", "collateral_usd": "50.00" } ``` The `_usd_pips` fields are the source of truth (10,000 pips = $1.00). The `_usd` fields are convenience values for display. ### Pagination All list endpoints use cursor-based pagination: | Param | Type | Default | Description | | ---------------- | ------- | ------- | -------------------------------------------- | | `limit` | integer | 25 | Results per page (1–100) | | `starting_after` | string | — | Cursor: return results after this object ID | | `ending_before` | string | — | Cursor: return results before this object ID | Response envelope: ```json { "data": [ ... ], "has_more": true } ``` `starting_after` and `ending_before` are mutually exclusive. ### Expanding sub-resources Some endpoints accept an `expand` query parameter to inline related sub-resources in the response, saving a follow-up request per item. The value is a comma-separated list of allowed expansion keys, documented per endpoint. ``` GET /prediction-markets/positions?expand=unwinds GET /prediction-markets/positions?expand=unwinds,foo,bar ``` Each expanded sub-resource appears as a top-level field on the parent object using the same shape it would have if fetched standalone. When the parent has no data for the requested sub-resource, the field is omitted. ### SDK method mapping If you're using `@dimes-dot-fi/sdk`, each endpoint maps to a client method: | Endpoint | SDK method | | --------------------------- | ------------------------------------- | | `GET /markets` | `client.getMarkets(params?)` | | `GET /markets/:ticker` | `client.getMarket(ticker)` | | `GET /contract-info` | `client.getContractInfo()` | | `POST /tokens` | Handled by `ApiKeyAuth` automatically | | `POST /draft-quotes` | `client.createDraftQuote(params)` | | `POST /promoted-quotes/:id` | `client.promoteDraftQuote(draftId)` | | `POST /quotes` | `client.createQuote(params)` | | `GET /positions` | `client.getPositions(params?)` | | `GET /limits` | `client.getLimits()` | The high-level `executeQuote()` function handles the full draft → promote flow with auto-retry and correction. See [SDK Installation](/for-developers/sdk-installation.md). *** ## 1. Markets ### List markets Returns markets currently eligible for trading. ``` GET /prediction-markets/markets ``` **Auth:** User JWT or partner API key **Query parameters:** | Param | Type | Default | Description | | ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- | | `accepting_new_positions` | boolean | — | Filter on whether **either** side is accepting new positions. `true` returns markets where YES or NO accepts. | | `limit` | integer | 25 | Max results (1–100) | | `starting_after` | string | — | Cursor: return results after this ticker | | `ending_before` | string | — | Cursor: return results before this ticker | | `category` | string | — | Filter by category | | `provider` | string | — | Filter: `polymarket` | | `status` | string | `active` | Filter: `active`, `closed`, `determined`, `finalized`, `disputed` | | `expand` | string | — | Comma-separated list of sub-resources to embed inline. Allowed values: `total_count`, `prices`. | **Response: `200 OK`** ```json { "data": [ { "accepting_new_positions": true, "id": "dm_mkt_abc123", "ticker": "will-btc-hit-100k-2025", "title": "Will BTC hit $100K?", "yes_sub_title": "Yes, before September 30", "category": "crypto", "rejection_reason_code": null, "sided_eligibility": { "yes": { "accepting_new_positions": true, "rejection_reason_code": null }, "no": { "accepting_new_positions": false, "rejection_reason_code": "QUOTE_SIDE_CAPACITY_EXCEEDED" } }, "status": "open", "tags": [ "crypto", "bitcoin" ], "close_time": "2025-09-30T00:00:00.000Z", "latest_enter_at": "2025-09-29T23:00:00.000Z", "provider": "polymarket", "min_notional_usd_pips": "10000", "min_notional_usd": "1.00", "leverage": { "min_bps": 20000, "max_yes_bps": 100000, "max_no_bps": 100000, "step_bps": 2500, "max_market_leverage_per_notional": { "yes": { "at100_usd_bps": 100000, "at500_usd_bps": 80000, "at1000_usd_bps": 60000, "at10000_usd_bps": 30000 }, "no": { "at100_usd_bps": 100000, "at500_usd_bps": 80000, "at1000_usd_bps": 60000, "at10000_usd_bps": 30000 } } }, "fees": { "origination_tiers": [ { "max_leverage_bps": 40000, "fee_bps": 100 }, { "max_leverage_bps": 70000, "fee_bps": 125 }, { "max_leverage_bps": 100000, "fee_bps": 150 } ], "lifetime_fee_apr_bps": 2000, "liquidation_fee_bps": 1000 }, "max_notional_yes_usd_pips": "500000000", "max_notional_yes_usd": "50000.00", "max_notional_no_usd_pips": "500000000", "max_notional_no_usd": "50000.00", "capacity_max_notional_yes_usd_pips": "400000000", "capacity_max_notional_yes_usd": "40000.00", "capacity_max_notional_no_usd_pips": "400000000", "capacity_max_notional_no_usd": "40000.00", "slippage_max_notional_yes_usd_pips": "350000000", "slippage_max_notional_yes_usd": "35000.00", "slippage_max_notional_no_usd_pips": "350000000", "slippage_max_notional_no_usd": "35000.00", "prices": { "yes_ask_price_usd": "0.51", "yes_ask_price_usd_pips": "5100", "yes_bid_price_usd": "0.49", "yes_bid_price_usd_pips": "4900", "no_ask_price_usd": "0.51", "no_ask_price_usd_pips": "5100", "no_bid_price_usd": "0.49", "no_bid_price_usd_pips": "4900" } } ], "has_more": true } ``` **Field reference:** | Field | Type | Description | | ----------------------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accepting_new_positions` | boolean | Whether this market is currently accepting new positions on **either** side. See `sided_eligibility` for per-side breakdown. | | `id` | string | Market ID | | `ticker` | string | Unique market ticker sourced from the upstream trading venue (e.g. the Polymarket slug). Use in quote requests. | | `title` | string or null | Human-readable market title | | `yes_sub_title` | string or null | Description of the "yes" outcome | | `category` | string | Market category | | `status` | string | `active`, `closed`, `determined`, `finalized`, or `disputed` | | `tags` | string\[] | Descriptive tags | | `close_time` | string (ISO 8601) or null | When the market resolves | | `latest_enter_at` | string (ISO 8601) or null | Latest time a new position can be opened | | `provider` | string | `polymarket` | | `rejection_reason_code` | string or null | Why this market is not accepting positions on **either** side (see table below). `null` if at least one side accepts. For per-side detail use `sided_eligibility.{yes,no}.rejection_reason_code`. | | `sided_eligibility.yes.accepting_new_positions` | boolean | Whether the YES side is accepting new positions. A market with healthy YES depth but thin/saturated NO can be `true` on YES and `false` on NO. | | `sided_eligibility.yes.rejection_reason_code` | string or null | Why the YES side is not accepting positions; `null` when accepting. Codes match the table below. | | `sided_eligibility.no.accepting_new_positions` | boolean | Whether the NO side is accepting new positions. | | `sided_eligibility.no.rejection_reason_code` | string or null | Why the NO side is not accepting positions; `null` when accepting. | | `min_notional_usd_pips` | string | Minimum notional (internal precision) | | `min_notional_usd` | string | Minimum notional (dollar display) | | `leverage.min_bps` | integer | Minimum leverage (20000 = 2x) | | `leverage.max_yes_bps` | integer | Maximum leverage on the YES side (100000 = 10x). May differ from `max_no_bps` on skewed markets due to per-side fee-tolerance caps. | | `leverage.max_no_bps` | integer | Maximum leverage on the NO side (100000 = 10x) | | `leverage.step_bps` | integer | Leverage must be a multiple of this (2500 = 0.25x steps) | | `leverage.max_market_leverage_per_notional.{yes,no}.at{100,500,1000,10000}_usd_bps` | integer | Maximum market leverage per side broken out by position notional ($100 / $500 / $1,000 / $10,000). Slippage grows with notional, so larger notionals have lower max leverage. A UI slider should publish the bucket that matches the user's selected notional. | | `fees.origination_tiers` | array | Fee tiers by leverage bracket | | `fees.lifetime_fee_apr_bps` | integer | Annual fee rate on borrowed capital, i.e. notional − collateral (2000 = 20% APR) | | `fees.liquidation_fee_bps` | integer | Fee charged on liquidation, applied to borrowed capital (1000 = 10%) | | `max_notional_yes_usd_pips` | string or null | Maximum notional available on the YES side (internal precision); `null` if capacity unknown | | `max_notional_yes_usd` | string or null | Maximum notional available on the YES side (dollar display) | | `max_notional_no_usd_pips` | string or null | Maximum notional available on the NO side (internal precision); `null` if capacity unknown | | `max_notional_no_usd` | string or null | Maximum notional available on the NO side (dollar display) | | `capacity_max_notional_yes_usd_pips` | string or null | Capacity-limited maximum notional for YES side (internal precision); `null` if capacity unknown | | `capacity_max_notional_yes_usd` | string or null | Capacity-limited maximum notional for YES side (dollar display) | | `capacity_max_notional_no_usd_pips` | string or null | Capacity-limited maximum notional for NO side (internal precision); `null` if capacity unknown | | `capacity_max_notional_no_usd` | string or null | Capacity-limited maximum notional for NO side (dollar display) | | `slippage_max_notional_yes_usd_pips` | string or null | Slippage-limited maximum notional for YES side (internal precision); `null` if slippage data unavailable | | `slippage_max_notional_yes_usd` | string or null | Slippage-limited maximum notional for YES side (dollar display) | | `slippage_max_notional_no_usd_pips` | string or null | Slippage-limited maximum notional for NO side (internal precision); `null` if slippage data unavailable | | `slippage_max_notional_no_usd` | string or null | Slippage-limited maximum notional for NO side (dollar display) | | `prices` | object or null | Latest bid/ask prices. Only present when `expand=prices` is requested. Null if no recent data. | | `prices.yes_ask_price_usd` | string | YES side ask price (dollar display) | | `prices.yes_ask_price_usd_pips` | string | YES side ask price (internal precision, 10000 pips = $1) | | `prices.yes_bid_price_usd` | string | YES side bid price (dollar display) | | `prices.yes_bid_price_usd_pips` | string | YES side bid price (internal precision) | | `prices.no_ask_price_usd` | string | NO side ask price (dollar display) | | `prices.no_ask_price_usd_pips` | string | NO side ask price (internal precision) | | `prices.no_bid_price_usd` | string | NO side bid price (dollar display) | | `prices.no_bid_price_usd_pips` | string | NO side bid price (internal precision) | > **Note:** `ticker` and "slug" refer to the same identifier — the terms are used interchangeably across our docs and integrations. **Rejection reason codes:** | Code | Meaning | | ------------------------------------ | ------------------------------------------------------------ | | `QUOTE_MARKET_NOT_ACTIVE` | Market status is not `active` | | `QUOTE_MARKET_UNSUPPORTED_CATEGORY` | Market category is not supported (only `crypto` and `sport`) | | `QUOTE_MARKET_OPEN_INTEREST_TOO_LOW` | Open interest is below the minimum threshold | | `QUOTE_MARKET_RISK_TOO_HIGH` | Market risk level is not `low` | | `QUOTE_TRADING_WINDOW_CLOSING` | Market is too close to its trading window end | | `QUOTE_HARD_EXIT_TOO_CLOSE` | *(deprecated, alias for QUOTE\_TRADING\_WINDOW\_CLOSING)* | | `QUOTE_ENTRY_EXCLUDED_SPORT` | Sport type is excluded from entry | | `QUOTE_ENTRY_EXCLUDED_MARKET_TYPE` | Market type (e.g. first-half moneyline) is excluded | | `QUOTE_ENTRY_SPREAD_TOO_WIDE` | Order book spread (absolute) exceeds maximum | | `QUOTE_ENTRY_DEPTH_TOO_LOW` | Order book depth is below minimum | | `QUOTE_ENTRY_BID_DEPTH_TOO_LOW` | Minimum bid depth across both sides is below threshold | | `QUOTE_ENTRY_MARKET_TOO_ELAPSED` | Market has passed too much of its lifetime | | `QUOTE_ENTRY_TOP_HOLDER_TOO_HIGH` | Top holder concentration exceeds maximum | | `QUOTE_ENTRY_VOLUME_TOO_LOW` | 24-hour trading volume is below minimum | | `QUOTE_ENTRY_PRICE_OUT_OF_RANGE` | Mid price is outside the allowed range | *** ### Search markets Search for markets by name, ticker, or token ID. ``` GET /prediction-markets/markets/search ``` **Auth:** User JWT or partner API key **Query parameters:** | Param | Type | Default | Description | | ------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `query` | string | — | **Required.** Search term: fuzzy match on title, exact match on ticker/slug or token ID | | `limit` | integer | 25 | Max results (1–100) | | `starting_after` | string | — | Cursor: return results after this ticker | | `ending_before` | string | — | Cursor: return results before this ticker | | `accepting_new_positions` | boolean | — | Filter on whether **either** side is accepting new positions. `true` returns markets where YES or NO accepts. | | `category` | string | — | Filter by category | | `provider` | string | — | Filter: `polymarket` or `kalshi` | | `status` | string | — | Filter: `active`, `closed`, `determined`, `finalized`, `disputed` | | `expand` | string | — | Comma-separated list of sub-resources to embed inline. Allowed values: `total_count`, `prices`. | **Search behavior:** The `query` parameter matches against multiple fields: | Field | Match type | | ------------ | -------------------------------- | | Market title | Case-insensitive substring match | | Ticker | Case-insensitive exact match | | Yes token ID | Exact match | | No token ID | Exact match | **Response: `200 OK`** — Same list envelope and market object shape as [List markets](#list-markets). ```json { "data": [ { "id": "dm_mkt_abc123", "ticker": "will-btc-hit-100k-2025", "title": "Will BTC hit $100K?", ... } ], "has_more": false } ``` *** ### Get market Returns a single market by ticker. Same shape as a list item (not wrapped in `data` array). ``` GET /prediction-markets/markets/{ticker} ``` **Auth:** User JWT or partner API key **Response: `200 OK`** — Single market object. **Errors:** | Status | Code | | ------ | --------------------------- | | 404 | `customer_market_not_found` | *** ### Get contract info Returns the vault contract address on Polygon and the public address of the authorized quote signer. Use this to verify that quote responses have not been tampered with by a man-in-the-middle. ``` GET /prediction-markets/contract-info ``` **Auth:** Public **Response: `200 OK`** ```json { "evm_chain_id": "137", "polygon_signer_address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "polygon_vault_contract_address": "0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc" } ``` **Field reference:** | Field | Type | Description | | -------------------------------- | ------ | ------------------------------------------------------- | | `evm_chain_id` | string | EVM chain ID (`"137"` for Polygon mainnet) | | `polygon_signer_address` | string | Checksummed address of the authorized signer on Polygon | | `polygon_vault_contract_address` | string | Checksummed address of the vault contract on Polygon | > **Tip:** These values are static. Fetch them once at startup and cache. #### Verifying a quote signature Before submitting an on-chain transaction, verify the quote's `contract_signature` was produced by the authorized signer. Reconstruct the message hash from the quote fields, recover the signer, and compare to `polygon_signer_address`: ```javascript import {ethers} from "ethers"; const messageHash = ethers.solidityPackedKeccak256( [ "string", "bytes16", "address", "bytes32", "uint256", "uint256", "uint32", "uint256", "uint16", "uint16", "uint16", "uint256", "uint256", "address", ], [ "CREATE_POSITION", quote.position_seed_hex, userWalletAddress, quote.polymarket_market_id, BigInt(quote.polymarket_token_id), BigInt(quote.collateral_usdc_units), quote.leverage_bps, BigInt(quote.notional_usdc_units), quote.origination_fee_bps, quote.lifetime_fee_apr_bps, quote.liquidation_fee_bps, BigInt(quote.signature_expiry), BigInt(contractInfo.evm_chain_id), contractInfo.polygon_vault_contract_address, ] ); const recoveredSigner = ethers.verifyMessage( ethers.getBytes(messageHash), quote.contract_signature ); if (recoveredSigner.toLowerCase() !== contractInfo.polygon_signer_address.toLowerCase()) { throw new Error("Signature verification failed"); } ``` Also verify that `polygon_vault_contract_address` and `evm_chain_id` match the corresponding fields in the quote. *** ## 2. Auth ### Generate token Generate a user-scoped JWT. The partner is responsible for verifying wallet ownership before calling. ``` POST /prediction-markets/tokens ``` **Auth:** Partner API key **Request:** ```json { "wallet_address": "0x1234...abcd" } ``` | Field | Type | Required | Validation | | ---------------- | ------ | -------- | -------------------------------------- | | `wallet_address` | string | yes | Valid EVM address or Solana public key | **Response: `201 Created`** ```json { "token": "eyJhbGciOiJIUzI1NiIs...", "expires_at": "2025-06-01T11:00:00.000Z" } ``` **Errors:** | Status | Code | | ------ | -------------------------------------- | | 401 | `unauthorized` | | 400 | `customer_auth_invalid_wallet_address` | *** ## 3. Quotes ### Create quote Create a new quote (step 1 of opening a position). Returns pricing, fees, liquidation parameters, and a transaction to sign. ``` POST /prediction-markets/quotes ``` **Auth:** User JWT **Rate limit:** 1 request per second for each authenticated wallet within a partner integration. **Request:** ```json { "market_ticker": "will-btc-hit-100k-2025", "effective_side": "yes", "leverage_bps": 50000, "notional_usd_pips": "250000000", "slippage_bps": 300, "provider": "polymarket", "allow_revision": false } ``` | Field | Type | Required | Validation | | ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_ticker` | string | yes | Market ticker | | `effective_side` | string | yes | `yes` or `no` | | `leverage_bps` | integer | yes | 20000–100000, multiple of 2500 | | `notional_usd_pips` | string | yes | Minimum `10000` | | `slippage_bps` | integer | yes | 100–1000 | | `provider` | string | no | `polymarket` (default) | | `allow_revision` | boolean | no | `false` (default). Opt in to server-side notional/leverage revision — see [Quote revisions](#quote-revisions). | | `order_type` | string | no | `fok` (default) or `fak`. `fok` is atomic fill-or-revert. `fak` enables partial-open — see [Partial-open (FAK)](#partial-open-fak). | | `min_fill_bps` | integer | no | Only valid with `order_type: "fak"`. Range `2000`–`5000`, multiple of `500` (5% steps). The minimum fill the user accepts before the floor leg is considered missed. Capped from below by `max(2000, ceil(MIN_COLLATERAL × 10000 / requested_collateral))` for small notionals. | **Response: `201 Created`** ```json { "id": "dm_off_abc123", "market_ticker": "will-btc-hit-100k-2025", "wallet_address": "0x1234...abcd", "effective_side": "yes", "provider": "polymarket", "leverage_bps": 50000, "notional_usd_pips": "250000000", "notional_usd": "25000.00", "entry_price_usd_pips": "6500", "entry_price_usd": "0.65", "origination_fee_bps": 125, "origination_fee_usd_pips": "625000", "origination_fee_usd": "0.63", "protocol_origination_fee_bps": 100, "protocol_origination_fee_usd_pips": "500000", "protocol_origination_fee_usd": "0.50", "partner_origination_fee_bps": 25, "partner_origination_fee_usd_pips": "125000", "partner_origination_fee_usd": "0.13", "polymarket_trading_fee_bps": 100, "liquidation_fee_bps": 1000, "current_liquidation_price_usd_pips": "3500", "current_liquidation_price_usd": "0.35", "expected_open_trading_fee_usd_pips": "225", "expected_open_trading_fee_usd": "0.02", "min_expected_position_token_units": "9900000", "total_user_amount_usd_pips": "5625000", "total_user_amount_usd": "562.50", "expires_at": "2025-06-01T10:05:00.000Z", "position_seed": "abc123...", "position_seed_hex": "0xa1b2c3d4e5f67890abcdef1234567890", "on_chain_position_key": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890", "swap_transaction": "base64-encoded-solana-tx...", "evm_chain_id": "137", "polymarket_market_id": "0xabcdef...", "contract_signature": "0xabc...", "polymarket_token_id": "52114319501245915516055106046884209969926127482827954674443846427813813222426", "polygon_vault_contract_address": "0x1234...5678", "signature_expiry": "1717236300", "revision": "accepted_as_requested", "requested_leverage_bps": 50000, "requested_notional_usd_pips": "250000000" } ``` | Field | Description | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Quote ID | | `market_ticker` | Market ticker | | `wallet_address` | Wallet address (from JWT) | | `effective_side` | `yes` or `no` | | `provider` | `polymarket` | | `leverage_bps` | Leverage in basis points | | `notional_usd_pips` / `_usd` | Notional exposure | | `entry_price_usd_pips` / `_usd` | Entry price | | `origination_fee_bps` | Combined fee rate at open (`protocol + partner`) | | `origination_fee_usd_pips` / `_usd` | Combined absolute fee at open | | `protocol_origination_fee_bps` | Protocol component of the origination fee in basis points | | `protocol_origination_fee_usd_pips` / `_usd` | Protocol component in absolute terms | | `partner_origination_fee_bps` | Partner component of the origination fee in basis points | | `partner_origination_fee_usd_pips` / `_usd` | Partner component in absolute terms | | `polymarket_trading_fee_bps` | Polymarket venue trading fee rate (applied to the expected open trading fee). `0` for Kalshi. The breakdown is only present on the offer response; historical position entries expose only the combined `origination_fee_*` values. | | `liquidation_fee_bps` | Fee charged on liquidation in basis points | | `current_liquidation_price_usd_pips` / `_usd` | Price triggering liquidation | | `expected_open_trading_fee_usd_pips` / `_usd` / `_usdc_units` | Expected exchange trading fee. Pass the `_usdc_units` value as the contract's `venueFeeUsdcUnits` parameter. Refunded in full on cancel or revert. | | `min_expected_position_token_units` | Minimum tokens expected (1,000,000 units = 1 token) | | `total_user_amount_usd_pips` / `_usd` | Total economic cost to open the position. Polymarket: collateral + origination fee + expected trading fee. The EVM contract pulls `collateral + origination fee + venueFee` via `safeTransferFrom` at `createPosition`. | | `expires_at` | Quote expiry (ISO 8601). The validity window is short and may change without notice — always read this field from the response and do not hardcode a duration. Requests submitted after this timestamp will be rejected; fetch a new quote instead. | | `position_seed` | Seed for on-chain account derivation | | `position_seed_hex` | Position seed as 0x-prefixed bytes16 hex — contract-ready value for `createPosition` | | `on_chain_position_key` | On-chain position key (bytes32) that will be derived on `createPosition`. Matches `on_chain_position_key` on the position response — use it to link a quote to its future position | | `swap_transaction` | Base64-encoded Solana transaction (Solana only) | | `evm_chain_id` | Chain ID for EVM signature (EVM only) | | `polymarket_market_id` | On-chain bytes32 Polymarket market identifier | | `contract_signature` | EIP-191 signature for contract create position | | `polymarket_token_id` | Polymarket ERC1155 conditional token ID for the selected side | | `polygon_vault_contract_address` | Vault contract address on Polygon | | `signature_expiry` | Unix timestamp when the EVM signature expires (EVM only). Always read this from the response — the validity window is short and may change without notice. | | `revision` | Signals whether the returned quote matches the request. One of `accepted_as_requested`, `notional_reduced`, `leverage_reduced`, or `notional_and_leverage_reduced`. See [Quote revisions](#quote-revisions). | | `requested_leverage_bps` | Leverage the caller sent in the request. Equal to `leverage_bps` when `revision === "accepted_as_requested"`. | | `requested_notional_usd_pips` | Notional the caller sent in the request. Equal to `notional_usd_pips` when `revision === "accepted_as_requested"`. | ### Partial-open (FAK) (coming soon) By default, quotes open atomically: the order either fills its full requested notional in one FOK match or reverts and refunds the user (no position is created). Some markets are too thin for the full size to land in a single match. Setting `order_type: "fak"` with `min_fill_bps < 10000` opts into the **partial-open** flow: 1. **Floor leg.** The backend posts an FOK sized at the user-requested floor (`floor_token_units = floor(target_token_units × min_fill_bps / 10000)`). If the floor FOK does not fill within the retry budget, the position is fully reverted and all collateral, origination fee, and prepaid venue fee are refunded. The customer gateway emits a `PARTIAL_OPEN_FLOOR_MISSED` notification. 2. **Chase the remainder.** Once the floor fills, the backend posts up to 3 FAK retries (5 seconds apart) for the remainder. Each fulfilled retry emits a `PARTIAL_OPEN_PROGRESS` notification with the cumulative fill amount. 3. **Finalize.** When the partial-open shared retry budget is exhausted (or cumulative fill reaches the full target), `finalizeOpenPartial` shrinks the on-chain position to the actually-filled size while preserving the originally signed leverage. Unused collateral, borrowed amount, and venue fee are refunded proportionally. ```json { "market_ticker": "will-btc-hit-100k-2025", "effective_side": "yes", "leverage_bps": 20000, "notional_usd_pips": "1000000000", "slippage_bps": 200, "order_type": "fak", "min_fill_bps": 5000 } ``` The position response on `GET /prediction-markets/positions` exposes `order_type` and `min_fill_bps` so the caller can confirm what the user signed. Subscribe to the customer gateway `notification` event to track progress — see [WebSocket: Notification events](/for-developers/websocket.md#notification-events-customer-gateway-only). ### Quote revisions By default (`allow_revision: false`), the API will not silently change the requested `notional_usd_pips` or `leverage_bps`. If the book or the on-chain collateral floor would force a reduction, the request is rejected with `400 QUOTE_REVISION_REQUIRED` and the response carries the parameters that *would* have been acceptable, so the caller can re-quote with values it explicitly agrees to: ```json { "error": { "type": "INVALID_REQUEST_ERROR", "code": "QUOTE_REVISION_REQUIRED", "message": "Offer cannot be honored at the requested parameters (...)", "params": { "revision": "leverage_reduced", "requested_leverage_bps": 80000, "requested_notional_usd_pips": "70000", "acceptable_leverage_bps": 70000, "acceptable_notional_usd_pips": "70000", "acceptable_collateral_usdc_units": "1000000" } } } ``` `params.revision` is one of `notional_reduced`, `leverage_reduced`, or `notional_and_leverage_reduced` — the kind of revision that would have been applied. The `acceptable_*` fields describe the largest position the API can produce at or below the original request; callers may resubmit with these exact values (and `allow_revision` may stay `false`). Pass `allow_revision: true` only if you want the server to revise the quote on your behalf — useful for integrations that already expect to compare `leverage_bps` / `notional_usd_pips` against `requested_leverage_bps` / `requested_notional_usd_pips` on the success response. With `allow_revision: true` the adjustments happen in a fixed order: 1. **Notional capping.** The capacity reservation fills as much of the requested notional as clears within the requested `slippage_bps`, preserving the requested leverage. Output: `revision === "notional_reduced"`. 2. **Leverage clamping.** Leverage may be lowered (rounded down to the nearest 2500 bps step) for either of two reasons: the capped notional at the requested leverage would produce `collateral_usdc_units < 1_000_000` (the vault's `CollateralBelowMinimum` floor), or the market's risk parameters cap leverage below what was requested. Output: `revision === "leverage_reduced"` (or `"notional_and_leverage_reduced"` if step 1 also fired, or if the risk cap forces notional down as well). 3. **Rejection.** If clamping would drop leverage below 15000 bps (1.5×), the API returns `400 Bad Request` with the `LIQUIDITY_INSUFFICIENT` error — the book is too thin to support a viable position. The invariant `notional_usdc_units === collateral_usdc_units × leverage_bps / 10_000` always holds on the returned quote (matches the EIP-712 payload signed by the API). **Errors:** See [Error Handling — Quotes](/for-developers/error-handling.md#post-quotes). ### Draft quotes Draft quotes compute the same pricing, fees, leverage, and liquidation numbers as a regular quote but do **not** reserve capacity or generate a chain signature. Use them for display purposes (e.g. showing estimated terms before the user commits) without consuming capacity that could block actual trades. ``` POST /prediction-markets/draft-quotes ``` **Auth:** User JWT **Rate limit:** 1 request per second for each authenticated wallet within a partner integration. **Request:** Identical to [Create quote](#create-quote) (same body fields and validation). **Response: `201 Created`** The response shape is the same as a regular quote with these differences: | Field | Value in draft quote | | ----------------------- | -------------------------------------------------------------- | | `id` | Draft quote ID (`dm_dro_...`) | | `contract_signature` | Empty string — no chain signature is generated | | `evm_chain_id` | Empty string | | `signature_expiry` | `"0"` | | `swap_transaction` | Absent | | `position_seed` | Empty string — no position seed is allocated | | `position_seed_hex` | Empty string | | `on_chain_position_key` | Empty string | | `expires_at` | Current timestamp (draft quotes do not have a validity window) | All pricing and fee fields (`entry_price_*`, `origination_fee_*`, `liquidation_*`, `total_user_amount_*`, etc.) are computed identically to a regular quote. A draft quote **cannot** be used to open a position directly. Instead, promote it to a real quote using the endpoint below. **Errors:** Same as [Error Handling — Quotes](/for-developers/error-handling.md#post-quotes), except capacity and position limit errors (`QUOTE_SIDE_CAPACITY_EXCEEDED`, `USER_POSITION_LIMIT_EXCEEDED`, etc.) are not returned since draft quotes do not reserve capacity. ### Promote draft quote Promote a draft quote to a real, executable quote. The backend loads the draft's parameters and re-runs the full quote pipeline, returning a signed quote that can be submitted on-chain. This is the recommended flow for the best user experience: 1. Call `POST /prediction-markets/draft-quotes` to get pricing — display it to the user 2. When the user is ready, call `POST /prediction-markets/promoted-quotes/{draft_quote_id}` 3. On success, immediately submit the signed quote to the contract If market conditions changed between the draft and promotion, the endpoint returns the same errors as a regular quote. The user can retry (step 1) to get fresh numbers. ``` POST /prediction-markets/promoted-quotes/{draft_quote_id} ``` **Auth:** User JWT (must match the wallet that created the draft) **Rate limit:** 1 request per second for each authenticated wallet within a partner integration. **Path parameters:** | Parameter | Type | Description | | ---------------- | ------ | ---------------------------------- | | `draft_quote_id` | string | Draft quote ID (from step 1 above) | **Request body:** Empty (all parameters are loaded from the draft). **Response: `201 Created`** Same shape as [Create quote](#create-quote) — a fully signed quote with `contract_signature`, `position_seed`, `signature_expiry`, and all pricing fields populated. **Errors:** | Status | Code | Description | | ------ | ---------------------------- | ----------------------------------------------------------------- | | `404` | — | Draft not found, or wallet/partner does not match the draft owner | | `400` | Same as regular quote errors | Market conditions changed since the draft | Promoting the same draft multiple times is allowed — each call creates a new independent quote. Only one can be used on-chain (position seeds are unique per quote). *** ## 4. Positions (User JWT) ### List positions List positions for the authenticated user. Scoped to `(wallet_address, partner_id)` from JWT. ``` GET /prediction-markets/positions ``` **Auth:** User JWT **Query parameters:** | Param | Type | Default | Description | | --------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | string | — | Filter by a single status: `pending`, `open`, `unwinding`, `closing`, `settling`, `closed`, `settled`, `liquidated`, `cancelled`. `open` includes positions currently being unwound for backwards compatibility. Mutually exclusive with `state`. | | `state` | string | — | Filter by lifecycle group: `active` (in-flight: `pending`, `open`, `unwinding`, `closing`, `settling`) or `inactive` (terminal: `closed`, `settled`, `liquidated`, `cancelled`). Mutually exclusive with `status`. | | `market_ticker` | string | — | Filter by market ticker | | `polymarket_token_id` | string | — | Filter by Polymarket conditional token ID | | `sort_by` | string | `created_at` | Sort field: `created_at`, `closed_at` | | `sort_direction` | string | `desc` | Sort order: `asc`, `desc` | | `limit` | integer | 25 | Max results (1–100) | | `starting_after` | string | — | Cursor: position ID | | `ending_before` | string | — | Cursor: position ID | | `expand` | string | — | Comma-separated list of related sub-resources to embed inline in each position. Allowed values: `unwinds`. See [Expanding sub-resources](#expanding-sub-resources). | **Response: `200 OK`** — Open position: ```json { "data": [ { "id": "dm_pos_abc123", "created_at": "2025-06-01T09:59:55.000Z", "on_chain_position_key": "0x1a2b3c...", "market_ticker": "will-btc-hit-100k-2025", "market_title": "Will BTC hit $100K?", "provider": "polymarket", "status": "open", "effective_side": "yes", "wallet_address": "0x1234...abcd", "effective_leverage_bps": 84000, "failure": null, "entry": { "collateral_usd_pips": "50000000", "collateral_usd": "50.00", "notional_usd_pips": "250000000", "notional_usd": "25000.00", "leverage_bps": 50000, "price_usd_pips": "6500", "price_usd": "0.65", "effective_entry_price_usd_pips": "6533", "effective_entry_price_usd": "0.6533", "effective_slippage_bps": 51, "origination_fee_bps": 125, "protocol_origination_fee_bps": 100, "partner_origination_fee_bps": 25, "origination_fee_usd_pips": "625000", "origination_fee_usd": "0.63", "opened_at": "2025-06-01T10:00:00.000Z", "open_latency_ms": 12500 }, "current": { "book_leverage_bps": 35000, "mark_price_usd_pips": "7000", "mark_price_usd": "0.70", "market_leverage_bps": 38500, "notional_usd_pips": "200000000", "notional_usd": "20000.00", "position_token_units": "384615", "collateral_usd_pips": "50000000", "collateral_usd": "50.00", "effective_collateral_usd_pips": "42000000", "effective_collateral_usd": "42.00", "unrealized_pnl_usd_pips": "-8000000", "unrealized_pnl_usd": "-8.00", "unrealized_pnl_bps": -1600, "net_unrealized_pnl_usd_pips": "-9200000", "net_unrealized_pnl_usd": "-9.20", "net_unrealized_pnl_bps": -1840, "position_value_usd_pips": "242000000", "position_value_usd": "24200.00" }, "risk": { "health_bps": 7500, "current_liquidation_price_usd_pips": "3200", "current_liquidation_price_usd": "0.32", "liquidation_buffer_bps": 5077, "liquidation_fee_bps": 1000, "margin_buffer_usd_pips": "5000000", "margin_buffer_usd": "500.00" }, "fees": { "lifetime_fee_apr_bps": 2000, "accrued_lifetime_fee_usd_pips": "1200000", "accrued_lifetime_fee_usd": "1.20", "pending_lifetime_fee_usd_pips": "300000", "pending_lifetime_fee_usd": "0.30", "accrued_venue_fee_usd_pips": "200000", "accrued_venue_fee_usd": "0.20", "total_fees_usd_pips": "2325000", "total_fees_usd": "2.33" }, "timing": { "is_settlement_pending": false, "is_voided": false, "market_close_time": "2025-09-30T00:00:00.000Z", "market_status": "active", "time_to_close_minutes": 172800 } } ], "has_more": false } ``` **Open position field reference:** | Field | Description | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Position identifier | | `created_at` | ISO 8601 timestamp when the position record was created | | `on_chain_position_key` | On-chain position key (bytes32) — pass directly to `requestClose` | | `market_ticker` | Market ticker | | `market_title` | Human-readable market title, or null | | `provider` | `polymarket` | | `status` | `pending`, `open`, `unwinding`, `closing`, `settling`, `closed`, `settled`, `liquidated`, `cancelled` | | `effective_side` | `yes` or `no` | | `wallet_address` | Wallet address that owns this position | | `effective_leverage_bps` | Time-weighted average structural leverage over position lifetime | | `failure` | `{ reason: string }` if the position transaction failed, otherwise `null` | | **entry** | Snapshot at position creation | | `entry.collateral_*` | User's original collateral | | `entry.notional_*` | Original notional | | `entry.leverage_bps` | Entry leverage (50000 = 5x) | | `entry.price_*` | Indicative entry price quoted on the offer | | `entry.effective_entry_price_*` | Actual fill price on the prediction market after execution. `null` until the on-chain fill is recorded. | | `entry.effective_slippage_bps` | Execution slippage between the offer's indicative price and the actual fill, in basis points. Signed: positive = adverse fill, negative = favorable. `null` until the fill is recorded. | | `entry.origination_fee_bps` | Combined fee rate at open (`protocol + partner`) | | `entry.protocol_origination_fee_bps` | Protocol portion of the origination fee in basis points | | `entry.partner_origination_fee_bps` | Partner portion of the origination fee in basis points | | `entry.origination_fee_*` | Absolute combined origination fee at open | | `entry.opened_at` | Open timestamp (null if still pending) | | `entry.open_latency_ms` | Milliseconds from position creation to on-chain open confirmation. `null` until fully opened. | | **current** | Live state (affected by force unwinds) | | `current.mark_price_*` | Current market mid price | | `current.notional_*` | Current notional (reduced by unwinds) | | `current.book_leverage_bps` | Current book-value leverage in basis points (20000 = 2x). Only changes when capital is returned via unwind. | | `current.market_leverage_bps` | Current market-value leverage in basis points, computed from the live oracle price. `null` when the position is insolvent (equity ≤ 0). | | `current.position_token_units` | Token quantity held (1,000,000 units = 1 token) | | `current.collateral_*` | Original collateral (unchanged by unwinds) | | `current.effective_collateral_*` | What user would net after repaying loan if closed now. Floored at 0. | | `current.unrealized_pnl_*` | PnL assuming close at mark price | | `current.unrealized_pnl_bps` | Unrealized PnL as return on equity in basis points | | `current.net_unrealized_pnl_*` | Unrealized PnL net of all fees (origination + pending lifetime + accrued venue) | | `current.net_unrealized_pnl_bps` | Net unrealized PnL as return on equity in basis points | | `current.position_value_*` | `tokens × mark_price` | | **risk** | Liquidation metrics | | `risk.health_bps` | Margin health 0–10000 (10000 at entry, 0 at liquidation) | | `risk.current_liquidation_price_*` | Price triggering liquidation | | `risk.liquidation_buffer_bps` | `(mark_price - liq_price) / mark_price × 10000` | | `risk.liquidation_fee_bps` | Fee on liquidation, applied to borrowed capital (1000 = 10%) | | `risk.margin_buffer_*` | Dollar distance to liquidation | | **fees** | Fee accruals | | `fees.lifetime_fee_apr_bps` | Annual rate on borrowed capital, i.e. notional − collateral (2000 = 20% APR) | | `fees.accrued_lifetime_fee_*` | Fees accrued since last unwind or open | | `fees.pending_lifetime_fee_*` | Uncollected fees from prior unwinds | | `fees.accrued_venue_fee_*` | Venue (Polymarket/Kalshi) trading fees paid so far on this position (open + any force-unwind legs) | | `fees.total_fees_*` | Rollup of all fees so far (origination + accrued lifetime + pending lifetime + accrued venue) | | **timing** | | | `timing.is_settlement_pending` | Whether settlement is pending (market resolved or voided, settlement not yet executed) | | `timing.is_voided` | Whether the market was voided (closed with no winner, 50/50 payout at $0.50 per token) | | `timing.market_close_time` | When the market resolves (null if no close time) | | `timing.market_status` | Market status (`active`, `closed`, `determined`, `finalized`, etc.). When `determined` or `finalized`, mark price reflects the settlement outcome ($1 or $0) | | `timing.time_to_close_minutes` | Minutes until close (null if no close time) | *** **Closed / settled / liquidated positions** replace `current`, `risk`, and `timing` with `close_reason` and `result`: ```json { "id": "dm_pos_xyz789", "created_at": "2025-06-01T09:59:55.000Z", "market_ticker": "will-eth-merge-succeed", "market_title": "Will the Ethereum merge succeed?", "provider": "polymarket", "status": "settled", "effective_side": "yes", "wallet_address": "0x1234...abcd", "effective_leverage_bps": 84000, "failure": null, "close_reason": "settled", "entry": { "collateral_usd_pips": "50000000", "collateral_usd": "50.00", "notional_usd_pips": "250000000", "notional_usd": "25000.00", "leverage_bps": 50000, "price_usd_pips": "6500", "price_usd": "0.65", "origination_fee_bps": 125, "protocol_origination_fee_bps": 100, "partner_origination_fee_bps": 25, "origination_fee_usd_pips": "625000", "origination_fee_usd": "0.63", "opened_at": "2025-06-01T10:00:00.000Z", "open_latency_ms": 12500 }, "result": { "closed_at": "2025-07-15T14:30:00.000Z", "realized_pnl_usd_pips": "15000000", "realized_pnl_usd": "15.00", "net_realized_pnl_usd_pips": "13375000", "net_realized_pnl_usd": "13.38", "net_realized_pnl_bps": 2675, "proceeds_usd_pips": "65000000", "proceeds_usd": "65.00", "collected_lifetime_fee_usd_pips": "1500000", "collected_lifetime_fee_usd": "1.50", "collected_liquidation_fee_usd_pips": "0", "collected_liquidation_fee_usd": "0.00" }, "fees": { "lifetime_fee_apr_bps": 2000, "total_lifetime_fee_usd_pips": "1500000", "total_lifetime_fee_usd": "1.50", "total_venue_fee_usd_pips": "200000", "total_venue_fee_usd": "0.20", "total_fees_usd_pips": "2325000", "total_fees_usd": "2.33" } } ``` > **Deprecated fields on closed `fees`:** `origination_fee_bps`, `protocol_origination_fee_bps`, `partner_origination_fee_bps`, `origination_fee_usd_pips`, `origination_fee_usd` are still emitted for backwards compatibility but duplicate the canonical values on `entry.*`. New integrations should read the origination fields from `entry` only. | Field | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `close_reason` | `closed`, `settled`, `liquidated`, `cancelled`, or `reverted` | | `result.closed_at` | When the position was finalized | | `result.realized_pnl_*` | Final PnL: `proceeds - collateral` | | `result.net_realized_pnl_*` | Realized PnL net of all fees (origination + lifetime + liquidation + venue) | | `result.net_realized_pnl_bps` | Net realized PnL as return on equity in basis points | | `result.proceeds_*` | USDC returned to user | | `result.collected_lifetime_fee_*` | Total lifetime fees collected | | `result.collected_liquidation_fee_*` | Liquidation fee (0 unless liquidated) | | `fees.total_lifetime_fee_*` | Total lifetime fees collected at close | | `fees.total_venue_fee_*` | Total venue (Polymarket/Kalshi) trading fees paid across the position lifetime (open + close/liquidate/settle + force-unwinds) | | `fees.total_fees_*` | Total blended fees (origination + lifetime + liquidation + venue) | *** ### Get position Get a single position. Must belong to the JWT's `(wallet_address, partner_id)`. ``` GET /prediction-markets/positions/{position_id} ``` **Auth:** User JWT **Query parameters:** | Param | Type | Description | | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `expand` | string | Comma-separated list of related sub-resources to embed inline. Allowed values: `unwinds`. See [Expanding sub-resources](#expanding-sub-resources). | **Response: `200 OK`** — Single position object (not wrapped in `data` array). **Errors:** | Status | Code | | ------ | ----------------------------- | | 404 | `customer_position_not_found` | *** ### Position unwinds (sub-resource) Each position has an unwinds (deleveraging) history. Fetch it inline by passing `expand=unwinds` to [List positions](#list-positions). Only completed unwinds are returned — pending or reverted unwinds are excluded. ```json { "data": [ { "id": "dm_pos_abc123", "...": "...", "unwinds": { "current_leverage_bps": 30000, "origination_leverage_bps": 60000, "originated_at": "2025-06-01T12:00:00.000Z", "data": [ { "executed_at": "2025-06-02T14:30:00.000Z", "before_leverage_bps": 60000, "after_leverage_bps": 30000 } ], "has_more": false } } ], "has_more": true } ``` **Field reference (each unwind event):** | Field | Type | Description | | --------------------- | ------- | -------------------------------------------------------- | | `executed_at` | string | ISO 8601 timestamp when the unwind was executed on-chain | | `before_leverage_bps` | integer | Leverage before unwind in basis points (20000 = 2x) | | `after_leverage_bps` | integer | Leverage after unwind in basis points (20000 = 2x) | The first unwind's `before_leverage_bps` equals the position's entry leverage. Each subsequent unwind's `before_leverage_bps` equals the previous unwind's `after_leverage_bps`. *** ## 5. Limits ### Partner limits Partner's global position limit and current usage. ``` GET /prediction-markets/partner-limits ``` **Auth:** Partner API key **Response: `200 OK`** ```json { "limit_usd_pips": "5000000000", "limit_usd": "500000.00", "usage_usd_pips": "1200000000", "usage_usd": "120000.00", "remaining_usd_pips": "3800000000", "remaining_usd": "380000.00" } ``` ### User limits Position limits for the authenticated user. ``` GET /prediction-markets/user-limits ``` **Auth:** User JWT **Response: `200 OK`** ```json { "limit_usd_pips": "100000000", "limit_usd": "10000.00", "usage_usd_pips": "25000000", "usage_usd": "2500.00", "remaining_usd_pips": "75000000", "remaining_usd": "7500.00" } ``` | Field | Description | | ----------------- | -------------------------------------------------- | | `limit_usd_*` | Maximum total notional across all open positions | | `usage_usd_*` | Sum of origination notional for all open positions | | `remaining_usd_*` | `limit - usage` | *** ## Endpoint Summary | Method | Path | Auth | Description | | ------ | ------------------------------------------------ | ------------------- | ---------------------- | | `GET` | `/v1/prediction-markets/markets` | User JWT or API key | List eligible markets | | `GET` | `/v1/prediction-markets/markets/search` | User JWT or API key | Search markets | | `GET` | `/v1/prediction-markets/markets/{ticker}` | User JWT or API key | Get market by ticker | | `GET` | `/v1/prediction-markets/contract-info` | Public | Contract verification | | `POST` | `/v1/prediction-markets/tokens` | Partner API key | Generate user JWT | | `POST` | `/v1/prediction-markets/quotes` | User JWT | Create quote | | `POST` | `/v1/prediction-markets/draft-quotes` | User JWT | Create draft quote | | `POST` | `/v1/prediction-markets/promoted-quotes/{id}` | User JWT | Promote draft to quote | | `GET` | `/v1/prediction-markets/positions` | User JWT | List positions | | `GET` | `/v1/prediction-markets/positions/{position_id}` | User JWT | Get position | | `GET` | `/v1/prediction-markets/partner-limits` | Partner API key | Partner limits | | `GET` | `/v1/prediction-markets/user-limits` | User JWT | User limits | *** ## Throttling All endpoints are rate-limited. The throttling scope and limit depend on authentication: | Auth type | Scope | Limit | | --------------- | -------------- | ------------------ | | API key | Per partner | 120 requests / min | | JWT | Per wallet | 60 requests / min | | Unauthenticated | Per IP address | 30 requests / min | **Exception:** The `POST /v1/prediction-markets/tokens` endpoint (JWT generation) is throttled at **180 requests per minute** per partner. ### Rate limit headers Every response includes: | Header | Description | | ----------------------- | ---------------------------------------------- | | `X-RateLimit-Limit` | Maximum requests allowed in the current window | | `X-RateLimit-Remaining` | Requests remaining in the current window | | `X-RateLimit-Reset` | Seconds until the current window resets | When throttled, the response also includes a `Retry-After` header with the number of seconds to wait before retrying. **`429 Too Many Requests`** ```json { "error": { "type": "RATE_LIMIT_ERROR", "code": "too many requests", "message": "Too Many Requests" } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.dimes.fi/for-developers/api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.