API Reference

Complete reference for all Dimes Multiply endpoints. For a guided walkthrough, see Quickstart.

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 the full comparison.

OpenAPI spec:

• Interactive Swagger UI: https://api.dimes.fi/v1/customer-docs (production) or https://api-sandbox.dimes.fi/v1/customer-docs (sandbox)

• Raw JSON: https://api.dimes.fi/v1/customer-docs-json (production) or 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):

{
  "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:

{
  "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.

---

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: true for markets accepting new positions, false for ineligible
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

{
  "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,
      "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
      },
      "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
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 (see table below)
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)
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: true for markets accepting new positions, false for ineligible
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.

{
  "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

{
  "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:

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:

{
  "wallet_address": "0x1234...abcd"
}

Field	Type	Required	Validation
wallet_address	string	yes	Valid EVM address or Solana public key

Response: 201 Created

{
  "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:

{
  "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.

Response: 201 Created

{
  "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.
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".

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:

{
  "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.

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 (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, 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 — 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.

Response: 200 OK — Open position:

{
  "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,
        "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"
      },
      "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	Fee rate at open
entry.origination_fee_*	Absolute 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)
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
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:

{
  "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,
    "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,
    "origination_fee_bps": 125,
    "origination_fee_usd_pips": "625000",
    "origination_fee_usd": "0.63",
    "total_lifetime_fee_usd_pips": "1500000",
    "total_lifetime_fee_usd": "1.50",
    "total_fees_usd_pips": "2125000",
    "total_fees_usd": "2.13"
  }
}

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 + liq)
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_fees_*	Total blended fees (origination + lifetime + liquidation)

---

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.

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. Only completed unwinds are returned — pending or reverted unwinds are excluded.

{
  "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

{
  "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

{
  "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

{
  "error": {
    "type": "RATE_LIMIT_ERROR",
    "code": "too many requests",
    "message": "Too Many Requests"
  }
}