Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:


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

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:

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.

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 /events/:event_ticker/markets

client.getEventMarkets(eventTicker, params?)

GET /series/:series_ticker/markets

client.getSeriesMarkets(seriesTicker, params?)

GET /markets/:ticker/positions

client.getMarketPositions(ticker, params?)

GET /events/:event_ticker/positions

client.getEventPositions(eventTicker, params?)

GET /series/:series_ticker/positions

client.getSeriesPositions(seriesTicker, params?)

GET /contract-info

client.getContractInfo()

POST /tokens

Handled by ApiKeyAuth automatically

POST /draft-quotes

client.createDraftQuote(params)

POST /promoted-quotes/:id

client.promoteDraftQuote(draftId, params?)

POST /quotes

client.createQuote(params)

GET /positions

client.getPositions(params?)

GET /positions/:id/transactions

client.getPositionTransactions(positionId)

GET /positions/:id/partial-closes

client.getPositionPartialCloses(positionId)

GET /user-limits

client.getUserLimits()

GET /partner-limits

client.getPartnerLimits()

GET /fee-rates

client.getFeeRates(params?)

POST /fee-reports

client.getFeeReport(params)

The high-level executeQuote() function handles the full draft → promote flow with auto-retry and correction; useQuote / useQuoteMachine wrap it for React. See SDK Installation and React Hooks.


1. Markets

List markets

Returns markets currently eligible for trading.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT or partner API key

Query parameters:

Param
Type
Default
Description

query

string

—

Free-text search term. When set, results are filtered to markets matching the term (see Search behavior below).

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

sort

string

ticker_asc

Sort order: ticker_asc (alphabetical), depth_desc (deepest markets first), discovered_at_desc (newest markets first by discovery date).

expand

string

—

Comma-separated list of sub-resources to embed inline. Allowed values: total_count, prices.

Search behavior:

Pass query to search. It 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

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.

capacity_max_notional_no_usd

string or null

Capacity-limited maximum notional for NO 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_yes_usd

string or null

Capacity-limited maximum notional for YES 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

category

string

Market category

close_time

string (ISO 8601) or null

When the market resolves

discovered_at

string (ISO 8601)

When this market was first discovered and listed on the platform. Sort by it with sort=discovered_at_desc to surface the newest markets first.

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 (250 = 2.5%)

fees.origination_tiers

array

Fee tiers by leverage bracket

id

string

Market ID

latest_enter_at

string (ISO 8601) or null

Latest time a new position can be opened

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.

leverage.max_no_bps

integer

Maximum leverage on the NO side (100000 = 10x)

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

integer

Minimum leverage (20000 = 2x)

leverage.step_bps

integer

Leverage must be a multiple of this (2500 = 0.25x steps)

max_notional_no_usd

string or null

Maximum notional you can open on the NO side right now — the lesser of slippage, capacity, your partner's remaining position limit, and the per-user position limit for a wallet with no open positions (dollar display)

max_notional_no_usd_pips

string or null

Maximum notional you can open on the NO side right now — the lesser of slippage, capacity, your partner's remaining position limit, and the per-user position limit for a wallet with no open positions (internal precision)

max_notional_yes_usd

string or null

Maximum notional you can open on the YES side right now — the lesser of slippage, capacity, your partner's remaining position limit, and the per-user position limit for a wallet with no open positions (dollar display)

max_notional_yes_usd_pips

string or null

Maximum notional you can open on the YES side right now — the lesser of slippage, capacity, your partner's remaining position limit, and the per-user position limit for a wallet with no open positions (internal precision)

min_collateral_usd

string

Minimum collateral (dollar display)

min_collateral_usd_pips

string

Minimum collateral (internal precision). A request with notional / leverage below this floor is rejected. The floor is partner-specific and can change over time — always read it from this endpoint per market; never hardcode the value shown in the example.

min_notional_usd

string

Minimum notional (dollar display)

min_notional_usd_pips

string

Minimum notional (internal precision). Partner-specific and subject to change — read it from this endpoint per market rather than hardcoding the example value.

polymarket

object

Polymarket identifiers for mapping this market onto Polymarket's own data feeds. Always present (all live markets are Polymarket-sourced).

polymarket.condition_id

string or null

Polymarket CTF condition ID. Use it to look the market up on Polymarket's CLOB and Gamma APIs. null for the rare market where Polymarket has not exposed a condition ID.

polymarket.no_token_id

string

Polymarket CLOB token ID (ERC1155 position token ID) for the NO outcome.

polymarket.slug

string

Polymarket market slug, matching the slug in Polymarket URLs and Gamma API responses. Same value as the legacy ticker field.

polymarket.yes_token_id

string

Polymarket CLOB token ID (ERC1155 position token ID) for the YES outcome.

prices

object or null

Latest bid/ask prices. Only present when expand=prices is requested. Null if no recent data.

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)

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)

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

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.

slippage_max_notional_no_usd

string or null

Slippage-limited maximum notional for NO 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_yes_usd

string or null

Slippage-limited maximum notional for YES 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

status

string

active, closed, determined, finalized, or disputed

tags

string[]

Descriptive tags

ticker

string

Deprecated — use polymarket.slug. Unique market ticker sourced from the upstream trading venue (the Polymarket slug). Still accepted in quote requests and path params.

title

string or null

Human-readable market title

yes_sub_title

string or null

Description of the "yes" outcome

Note: ticker and "slug" refer to the same identifier — the terms are used interchangeably across our docs and integrations.

Rejection reason codes:

These are the values the rejection_reason_code field (market-level and per-side) can take. They are distinct from the codes a live POST /quotes call throws — those are in Error Handling. Both are UPPERCASE, unlike an error response's lowercase error.code.

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_UNSUPPORTED_CRYPTO_ASSET

Crypto market whose underlying asset has no supported price feed

QUOTE_MARKET_UNSUPPORTED_SPORT

Sport market whose sport is not recognised, so no hard-exit deadline can be set

QUOTE_MARKET_RISK_TOO_HIGH

Market risk level is not low

QUOTE_MAX_LEVERAGE_TOO_LOW

Model max leverage for this market has fallen below the tradable minimum

QUOTE_TRADING_WINDOW_CLOSING

Market is at or inside its hard-exit deadline — no new entries

QUOTE_EVENT_NOT_STARTED

Event has not started and pre-game entry is not allowed for this market

QUOTE_SIDE_CAPACITY_EXCEEDED

This side is at capacity

QUOTE_ENTRY_BOOK_ONE_SIDED

Order book is missing or one-sided

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_VOLUME_TOO_LOW

24-hour trading volume is below minimum

QUOTE_ENTRY_PRICE_OUT_OF_RANGE

Mid price is outside the allowed range

NOTIONAL_SELECTOR_BELOW_MIN_NOTIONAL

Liquidity within slippage is too thin to fill even the minimum size on this side

NOTIONAL_SELECTOR_PREGAME_INSUFFICIENT_LIQUIDITY

Pre-game market lacks enough estimated live liquidity on this side

RISK_ENGINE_MARKET_DISABLED

Market disabled by an admin kill switch


Get market

Returns a single market by ticker. Same shape as a list item (not wrapped in data array).

SDK (@dimes-dot-fi/sdk):

Auth: User JWT or partner API key

Response: 200 OK — Single market object.

Errors:

Status
Code

404

customer_market_not_found


List markets for an event

Returns the markets belonging to a single event — the real-world happening a market resolves against, such as one game or one hourly price window. An event usually holds several markets (moneyline, spread, totals, and so on).

Get the event_ticker from the event.ticker field of any market.

Auth: User JWT or partner API key

Query parameters: identical to List markets — accepting_new_positions, category, provider, status, query, sort, limit, starting_after, ending_before, and expand.

Response: 200 OK — Same paginated envelope and same market objects as GET /markets.

Errors:

Status
Code

404

customer_event_not_found


List markets for a series

Returns the markets belonging to a single series, across every event in that series. A series is the recurring template an event belongs to — for example the 5-minute BTC up/down series, which produces a new event every 5 minutes.

Get the series_ticker from the event.series_ticker field of any market. It is null for markets whose event has no series.

Auth: User JWT or partner API key

Query parameters: identical to List markets.

Response: 200 OK — Same paginated envelope and same market objects as GET /markets. A series commonly holds more markets than fit on one page, so paginate with starting_after.

Errors:

Status
Code

404

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

SDK (@dimes-dot-fi/sdk):

Auth: Public

Response: 200 OK

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_usdc_token_address

string

Checksummed address of the pUSD stablecoin token — the only token accepted as collateral. Use it as the transfer target when funding a position

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:

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.

SDK (@dimes-dot-fi/sdk):

Auth: Partner API key

Request:

Field
Type
Required
Validation

wallet_address

string

yes

Valid EVM address or Solana public key

Response: 201 Created

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.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT

Rate limit: 1 request per second for each authenticated wallet within a partner integration.

Request:

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_amount_usd_pips

string

yes

Minimum 10000

slippage_bps

integer

yes

100–1000

provider

string

no

polymarket (default)

allow_partial_fill

boolean

no

false (default) — the order is atomic (fully filled or reverted). true opts into partial-open: the position opens at the actually-filled size. See Partial-Open (FAK).

risk_mode

string

no

adaptive (default) or committed. committed asks for a fixed, published deleveraging ladder backed by extra margin — answered in committed mode or rejected, never silently downgraded. Beta feature, enabled per partner. Ignored on draft quotes. See Committed Risk Mode.

min_fill_bps

integer

no

Only valid with allow_partial_fill: true. Range 2000–7000, multiple of 500 (5% steps). The minimum fraction of the requested notional the user will accept. Capped from below by max(2000, ceil(MIN_COLLATERAL × 10000 / requested_collateral), ceil(MIN_NOTIONAL × 10000 / requested_notional)) so a worst-case partial fill cannot drop below the minimum collateral or the minimum notional — see quote_min_fill_bps_below_floor in error handling.

Response: 201 Created

Expanding max gain (?expand=max_gain)

Add ?expand=max_gain to any quote endpoint (/quotes, /draft-quotes, /promoted-quotes/{id}) to include a max_gain object — the expected profit on a win (profit over principal). It is omitted unless requested.

gross_max_gain is the position's value on a win (tokens redeemed at $1 via settlement) minus the notional, before fees. net_max_gain also subtracts the open trading fee and origination fee. It assumes settlement (no exit trading fee) and excludes time-based lifetime fees, so it is an upper bound — and may be negative for high-price entries.

Field
Description

authority_public_key

Wallet address (from JWT)

collateral_usdc_units

Collateral in USDC units (1,000,000 units = $1). Contract-ready value for createPosition

contract_signature

EIP-191 signature for contract create position

current_liquidation_price_usd_pips / _usd

Price triggering liquidation

effective_side

yes or no

entry_price_usd_pips / _usd

Entry price

evm_chain_id

Chain ID for EVM signature (EVM only)

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.

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.

id

Quote ID

leverage_bps

Leverage in basis points

liquidation_fee_bps

Fee charged on liquidation in basis points

market_ticker

Market ticker

min_expected_position_token_units

Minimum tokens expected (1,000,000 units = 1 token)

notional_amount_usd_pips / _usd / _usdc_units

Notional exposure

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

origination_fee_bps

Combined fee rate at open (protocol + partner)

origination_fee_usd_pips / _usd / _usdc_units

Combined absolute fee at open

partner_origination_fee_bps

Partner component of the origination fee in basis points (deprecated — prefer builder code fees)

partner_origination_fee_usd_pips / _usd / _usdc_units

Partner component in absolute terms (deprecated — prefer builder code fees)

partner_trading_fee_bps

Your Polymarket builder taker fee rate (flat % of notional). 0 when no builder code is configured

partner_trading_fee_usd_pips / _usd / _usdc_units

Your builder taker fee in absolute terms. Included in expected_open_trading_fee_*

polygon_vault_contract_address

Vault contract address on Polygon

polymarket_market_id

On-chain bytes32 Polymarket market identifier

polymarket_token_id

Polymarket ERC1155 conditional token ID for the selected side

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 quote response; historical position entries expose only the combined origination_fee_* values.

position_seed

Seed for on-chain account derivation

position_seed_hex

Position seed as 0x-prefixed bytes16 hex — contract-ready value for createPosition

protocol_origination_fee_bps

Protocol component of the origination fee in basis points

protocol_origination_fee_usd_pips / _usd / _usdc_units

Protocol component in absolute terms

provider

polymarket

risk_mode

adaptive or committed — the mode this quote was actually issued in. A committed quote must be opened through createPositionWithMargin. See Committed Risk Mode

margin_usd / margin_usdc_units

Extra margin posted on top of collateral for a committed quote. "0" on adaptive quotes. Already included in total_user_amount_*

committed_unwinds

The committed deleveraging ladder priced for this quote (availability, required margin, debt-clear price, and the rungs), or available: false when the mode cannot be offered. Omitted entirely while the beta feature is off for your partner

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.

swap_transaction

Base64-encoded Solana transaction (Solana only)

total_user_amount_usd_pips / _usd / _usdc_units

Total economic cost to open the position. Polymarket: collateral + origination fee + expected trading fee, plus the committed-mode margin when risk_mode is committed. The EVM contract pulls exactly this amount via safeTransferFrom at open — approve it in full.

authority_public_key

Wallet address (from JWT)

Committed risk mode

Set risk_mode: "committed" on a quote to open on a fixed ladder of price-triggered unwinds shown up front, backed by extra margin held in the vault, instead of the adaptive risk engine. The quote then carries risk_mode, margin_usd*, and committed_unwinds, and must be opened through createPositionWithMargin. Committed mode is a beta feature — while it is off for your partner account, risk_mode: "committed" is rejected with beta_feature_not_enabled and committed_unwinds is omitted. The full field reference, the promotion rules, and the rejection reasons are on the dedicated Committed Risk Mode page.

Partial-open (FAK)

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). For thinner markets, set allow_partial_fill: true (optionally with a min_fill_bps floor) to open at the actually-filled size instead.

The quote and position responses echo allow_partial_fill and min_fill_bps so the caller can confirm what the user signed. The full lifecycle (floor leg, FAK retries, finalizeOpenPartial shrink/refund), the min_fill_bps floor rules, the progress/floor-missed notifications, and the quote_min_fill_bps_below_floor rejection are documented on the dedicated Partial-Open (FAK) page.

The invariant notional_usdc_units === collateral_usdc_units × leverage_bps / 10_000 always holds on the returned quote, and matches the payload the API signed.

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.

SDK (@dimes-dot-fi/sdk):

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)

risk_mode

Always adaptive — a draft carries no mode (see below)

margin_usdc_units

Always "0" — a draft is always priced as adaptive

All pricing and fee fields (entry_price_*, origination_fee_*, liquidation_*, total_user_amount_*, etc.) are computed identically to a regular quote.

A draft has no risk mode: risk_mode on the request body is ignored, and the response always reports risk_mode: "adaptive" with margin_usdc_units: "0". The draft still carries a full committed_unwinds block, so you can show the user both sets of terms side by side — the ladder, its margin, and the total they would pay (total_user_amount_usdc_units + committed_unwinds.margin_required_usdc_units) — before they choose. The choice is made when you promote, and the draft's ladder is the one the promoted quote honours. See Committed Risk Mode.

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.

Recommended flow:

  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.

SDK (@dimes-dot-fi/sdk):

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: All pricing parameters are loaded from the draft. One optional field:

Field
Type
Required
Validation

risk_mode

string

no

adaptive (default) or committed. This is where the mode is chosen — a draft carries none. Promote with committed to open on the ladder the draft showed. See Committed Risk Mode.

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

400

quote_committed_risk_mode_unavailable

Promoted with risk_mode: "committed" but the draft has no ladder — committed mode was unavailable when the draft was priced. Promote as adaptive, or take a fresh draft.

400

quote_committed_plan_more_restrictive

The ladder priced now is harsher than the one the draft showed, so the draft's terms cannot be honoured. Carries max_leverage_bps (retry at that leverage) plus the margin and rungs priced now (both null if the mode is no longer available at all).

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.

SDK (@dimes-dot-fi/sdk):

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 or partially closed 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.

ticker

string

—

Deprecated — use GET /markets/{ticker}/positions instead. Filter by market ticker. Still supported; no removal planned.

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, planned_unwinds, total_count. See Expanding sub-resources.

Response: 200 OK — Open position:

Open position field reference:

Field
Description

created_at

ISO 8601 timestamp when the position record was created

close_attempt

Present when a requested close was deferred because the market resolved before the shares could be sold: { outcome: "deferred", reason: "awaiting_settlement", deferred_at: <ISO 8601> }. The remaining tokens are redeemed at settlement. null for any open position without a deferred close.

effective_leverage_bps

Time-weighted average structural leverage over position lifetime

effective_side

yes or no

failure

{ reason: string } if the position transaction failed, otherwise null

id

Position identifier

market_ticker

Market ticker

market_title

Human-readable market title, or null

on_chain_position_key

On-chain position key (bytes32) — pass directly to requestClose or requestPartialClose

provider

polymarket

status

pending, open, unwinding, closing, settling, closed, settled, liquidated, cancelled

wallet_address

Wallet address that owns this position

entry

Snapshot at position creation

entry.collateral_*

User's original collateral

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 quote's indicative price and the actual fill, in basis points. Signed: positive = adverse fill, negative = favorable. null until the fill is recorded.

entry.initial_fill_bps

How much of the requested size was actually filled at open, in basis points (10000 = 100%). Frozen at open. Use this for an "opened at X% of requested" indicator. Frozen at open — it does not change when the position is partially closed. null until the open fill is recorded.

entry.leverage_bps

Entry leverage (50000 = 5x)

entry.locked_margin_usdc_units

Extra margin locked in the vault at open, in USDC units. "0" on adaptive positions. Released at any terminal state: it joins the payout waterfall on close, settle or liquidation (so it absorbs a shortfall before protocol capital does), and is refunded in full if the position is cancelled or reverted.

entry.risk_mode

adaptive (the risk engine manages leverage) or committed (the position follows the ladder fixed at quote time). See Committed Risk Mode

entry.notional_*

Original notional

entry.open_latency_ms

Milliseconds from position creation to on-chain open confirmation. null until fully opened.

entry.opened_at

Open timestamp (null if still pending)

entry.origination_fee_*

Absolute combined origination fee at open

entry.origination_fee_bps

Combined fee rate at open (protocol + partner)

entry.partner_origination_fee_bps

Partner portion of the origination fee in basis points (deprecated — prefer builder code fees)

entry.price_*

Indicative entry price quoted at open

entry.protocol_origination_fee_bps

Protocol portion of the origination fee in basis points

current

Live state (affected by force unwinds)

current.book_leverage_bps

Current book-value leverage in basis points (20000 = 2x). Only changes when capital is returned via unwind.

current.collateral_*

Original collateral (unchanged by unwinds)

current.effective_collateral_*

What user would net after repaying loan if closed now. Floored at 0.

current.mark_price_*

Current market mid price

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.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.notional_*

Current notional (reduced by unwinds)

current.position_token_units

Token quantity held (1,000,000 units = 1 token)

current.position_value_*

tokens × mark_price

current.remaining_bps

Fraction of the originally opened size still held, in basis points (10000 = 100%). Legitimately decreases after each partial close (e.g. 7000 = 70% remaining after a 30% close) — not a fill problem. null until the open fill is recorded.

current.unrealized_pnl_*

PnL assuming close at mark price

current.unrealized_pnl_bps

Unrealized PnL as return on equity in basis points

risk

Liquidation metrics

risk.current_liquidation_price_*

Price triggering liquidation

risk.health_bps

Margin health 0–10000 (10000 at entry, 0 at liquidation)

risk.liquidation_buffer_bps

(mark_price - liq_price) / mark_price × 10000

risk.liquidation_fee_bps

Fee on liquidation, applied to borrowed capital (250 = 2.5%)

risk.margin_buffer_*

Dollar distance to liquidation

fees

Fee accruals

fees.accrued_lifetime_fee_*

Fees accrued since last unwind or open

fees.accrued_venue_fee_*

Venue (Polymarket/Kalshi) trading fees paid so far on this position (open + any force-unwind legs)

fees.lifetime_fee_apr_bps

Annual rate on borrowed capital, i.e. notional − collateral (2000 = 20% APR)

fees.pending_lifetime_fee_*

Uncollected fees from prior unwinds

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

Where the market sits on the road to settlement: none, awaiting_resolution, settling, voided, or unresolved_upstream. See below

timing.time_to_close_minutes

Minutes until close (null if no close time)

Settlement states

A market stops trading before its result exists on chain, so a position can sit open with nothing to redeem for a while. settlement_state tells you which part of that road the market is on:

Value
What it means

none

The market is still trading. Nothing is pending.

awaiting_resolution

The market has closed and the outcome is decided, but the prediction market provider has not published the result on chain yet. Nothing can be redeemed. Positions stay open.

settling

The result is published and we are settling open positions. This is the state where is_settlement_pending is true.

voided

The market was voided. Every token pays out at $0.50 regardless of side.

unresolved_upstream

The market disappeared from the provider before publishing a result and may never resolve.

awaiting_resolution is normal and often lasts hours — sports markets in particular close when the game ends but only resolve once the provider's oracle reports. Show it to your users as "waiting to settle" rather than treating it as an error or a stuck position.

Note that is_settlement_pending is false during awaiting_resolution: it means "the result is in and we are settling", not "settlement is expected at some point". Use settlement_state when you need to tell those apart.


Closed / settled / liquidated positions replace current, risk, and timing with close_reason and result:

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

fees.total_fees_*

Total blended fees (origination + lifetime + liquidation + venue)

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)

result.closed_at

When the position was finalized

result.collected_lifetime_fee_*

Total lifetime fees collected

result.collected_liquidation_fee_*

Liquidation fee (0 unless liquidated)

result.exit_notional_*

Volume-weighted notional realized across all unwinds and the final close (Σ shares sold × fill price). Pairs with entry.notional_* for an entry-vs-exit view. Null for reverted/cancelled positions (no shares were ever sold).

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_*

pUSD returned to user

result.realized_pnl_*

Final PnL: proceeds - collateral

revert_reason

Why a reverted open failed. Non-null only when close_reason is reverted: exchange_unavailable (venue was temporarily unavailable — safe to retry), slippage_exceeded (price moved beyond tolerance before the order filled), or unknown. Null otherwise.


Get position

Get a single position. Must belong to the JWT's (wallet_address, partner_id).

SDK (@dimes-dot-fi/sdk):

Auth: User JWT

Query parameters:

Param
Type
Description

expand

string

Comma-separated list of related sub-resources to embed inline. Allowed values: unwinds, planned_unwinds. See Expanding sub-resources.

Response: 200 OK — Single position object (not wrapped in data array).

Errors:

Status
Code

404

customer_position_not_found


List your positions for a market

Returns the authenticated user's positions on a single market. Supersedes the deprecated ticker query parameter on List positions.

Auth: User JWT

Query parameters: identical to List positions — status, state, sort_by, sort_direction, limit, starting_after, ending_before, and expand.

Response: 200 OK — Same paginated envelope and same position objects as GET /positions. Returns an empty page if you hold no positions on that market.

Errors:

Status
Code

404

customer_market_not_found


List your positions for an event

Returns the authenticated user's positions across every market on a single event — for example, every position you hold on tonight's game.

Get the event_ticker from the event.ticker field of any market.

Auth: User JWT

Query parameters: identical to List positions.

Response: 200 OK — Same paginated envelope and same position objects as GET /positions.

Errors:

Status
Code

404

customer_event_not_found


List your positions for a series

Returns the authenticated user's positions across every market in a single series, spanning all of that series' events.

Get the series_ticker from the event.series_ticker field of any market.

Auth: User JWT

Query parameters: identical to List positions.

Response: 200 OK — Same paginated envelope and same position objects as GET /positions.

Errors:

Status
Code

404

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

A committed-mode position also has a ladder: the deleveraging steps agreed at quote time, most of which have not happened yet. Fetch it with expand=planned_unwinds, which returns the same row shape under a planned_unwinds key. Both expansions can be requested together (expand=unwinds,planned_unwinds); planned_unwinds is empty on adaptive positions. Executed rows describe what happened; ladder rows describe what was promised — nothing guarantees an executed unwind lines up with a rung, so keep the two lists apart rather than merging them.

Field reference (each unwind event):

Field
Type
Description

after_leverage_bps

integer

Leverage after unwind in basis points (20000 = 2x). On a ladder row, the leverage the step takes the position down to

before_leverage_bps

integer

Leverage before unwind in basis points (20000 = 2x)

executed_at

string

ISO 8601 timestamp when the unwind was executed on-chain. null on a ladder step that has not fired

status

string

executed — a deleverage that landed on-chain. planned — a ladder step still ahead of the position. triggered — a ladder step whose trigger price was reached (executed_at is stamped). superseded — a ladder step that can no longer fire, because a partial close already took the position below its target.

trigger_price_usd_pips

string

The price that fires this ladder step, in USD pips (10000 pips = $1). null on executed rows

reason

string

Machine-readable code for the market signal that triggered the risk model to deleverage this position. null for unwinds not tied to a risk-model run (e.g. manual admin deleveraging). See the reason reference below.

reason_detail

string

Human-readable, customer-facing sentence explaining reason (e.g. "The bid-ask spread widened sharply beyond its recent baseline, signalling thinning liquidity."). Display this directly; null whenever reason is null.

reason values:

Value
Meaning

spread_blowout

The bid-ask spread widened sharply beyond its recent baseline, signalling thinning liquidity.

spread_spike

The bid-ask spread jumped abruptly to several times its baseline.

spread_warning

The bid-ask spread widened past an elevated warning level.

depth_decay

Resting order-book depth fell well below its recent peak.

depth_drain

Order-book depth across the market dropped sharply from entry levels.

depth_entry_drain

Order-book depth fell far below the level present when the position opened.

price_drop_warning

The position's side ticked down — an early adverse-price signal.

price_drop_moderate

The position's side fell moderately against the position.

price_drop_severe

The position's side fell sharply against the position.

price_drop_full_exit

The position's side dropped far enough to fully deleverage rather than step down.

activity_surge

A surge in trading activity signalled elevated volatility.

cancel_acceleration

A spike in order cancellations signalled market makers pulling liquidity.

large_holder

A large holder entered or materially grew their position in this market.

position_exposure

The position grew large relative to available exit liquidity.

last_trade_divergence

The last traded price diverged materially from the current bid.

crypto_move

The underlying crypto price moved beyond its risk threshold.

game_start

The underlying game went live.

lead_change

The lead changed in the underlying game.

post_hard_exit_losing

Risk was re-evaluated after a hard-exit event on the losing side.

stale_refresh

A scheduled periodic risk refresh, not triggered by a specific market event.

unknown

The position was deleveraged by the risk engine; the specific signal was not attributed.

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. Ladder rows chain the same way, except a superseded step does not advance the chain — it can never fire.


Position transactions (sub-resource)

Returns every on-chain transaction tied to a position, grouped by operation type, so you can give users full visibility into the on-chain transfers behind their position. Each group is an object with a transactions array; transactions that route through an exchange (open, close, liquidation, settle, force_unwind) also include the on-chain hashes of their nested exchange (CLOB/DEX) fills. Only transactions that landed and finalized on-chain are returned — pending, failed, and reverted transactions are excluded.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT — must belong to the JWT's (wallet_address, partner_id).

Response: 200 OK

Each group is an object with a transactions array (wrapped in an object so the response can carry per-group metadata in the future without a breaking change).

Field reference:

Field
Type
Description

cancel

object

Transactions that cancelled the position before it opened.

cancel_request

object

The close request transaction the position owner submitted on-chain.

close

object

Transactions that closed the position, including the finalize-close transaction.

force_unwind

object

Transactions that force-unwound (deleveraged) the position, including the finalize-unwind transaction.

liquidation

object

Transactions that liquidated the position, including the finalize-liquidation transaction.

open

object

Transactions that opened the position, including the finalize-open transaction.

redemption

object

Transactions that redeemed settled position tokens.

revert

object

Transactions that reverted a failed open back to the protocol.

settle

object

Transactions that settled the position, including the finalize-settle transaction.

Every group object has a single transactions field (object[]) holding the entries below.

Each transaction object:

Field
Type
Description

exchange_transaction_hashes

string[]

On-chain hashes of the nested exchange (CLOB/DEX) fills. Present only for exchange-routed transactions.

transaction_hash

string

On-chain transaction hash (EVM transaction hash or Solana signature).

Errors:

Status
Code

404

customer_position_transactions_not_found


Position partial closes (sub-resource)

Beta feature — enabled per partner. Until partial close is enabled for your API key this endpoint returns 400 beta_feature_not_enabled. Contact us to have it enabled.

Returns the executed partial-close history for a position, in chronological order — one entry per partial close, with the tokens sold, the average realized sale price, the proceeds, the protocol capital repaid, the owner payout, and the size and leverage left afterwards. Only partial closes that finalized on-chain are returned — pending and reverted partial closes are excluded.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT — must belong to the JWT's (wallet_address, partner_id).

Response: 200 OK

Field reference (each entry in data):

Field
Type
Description

executed_at

string

ISO 8601 timestamp when the partial close settled on-chain.

sold_token_units

string

Token units sold in this partial close (1,000,000 units = 1 token).

average_sale_price_*

string

Average realized sale price for the sold slice (net of venue fee).

sale_proceeds_*

string

Gross sale proceeds received for the sold slice.

capital_repaid_*

string

Protocol capital repaid from the proceeds.

user_payout_*

string

Amount paid out to the position owner from the proceeds.

remaining_position_token_units

string

Position token units still held after this partial close.

new_leverage_bps

number or null

Book leverage after this partial close (20000 = 2x). null if not recorded on-chain.

Errors:

Status
Code

400

beta_feature_not_enabled

404

customer_position_not_found


5. Limits

Partner limits

Partner's global position limit and current usage.

SDK (@dimes-dot-fi/sdk):

Auth: Partner API key

Response: 200 OK

User limits

Position limits for the authenticated user.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT

Response: 200 OK

Field
Description

limit_usd_*

Maximum total notional across all open positions

remaining_usd_*

limit - usage

usage_usd_*

Sum of origination notional for all open positions


6. Fees

These endpoints let you reproduce a quote's economics client-side — the fee schedule, and a full pre-quote cost/profit breakdown — without creating a quote.

Fee rates

The protocol fee schedule plus your partner's fee components. Pass ticker to also include that market's venue (Polymarket) fee fields.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT

Query parameters:

Parameter
Required
Description

ticker

No

Market ticker. When set, the response includes market.

Response: 200 OK

Field
Description

origination_fee_tiers

Leverage-tiered protocol origination fee. Pick the first tier whose max_leverage_bps >= leverage_bps.

contract_max_origination_fee_bps

On-chain cap on the combined (protocol + partner) origination fee.

lifetime_fee_apr_bps

Lifetime fee APR, charged on protocol capital over time.

liquidation_fee_bps

Liquidation fee, on protocol capital.

partner_origination_fee_bps

Your origination fee component, added on top of the protocol tier. (deprecated — prefer builder code fees)

partner_trading_fee_bps

Your Polymarket builder taker fee (flat % of notional).

market

Per-market venue fee fields. Only present when ticker is supplied.

Fee report

A full cost and max-gain breakdown for a hypothetical position, computed from notional + leverage using the market's fee rates. Does not create a quote and does not sign anything. The liquidation price is a deterministic at-entry estimate; the binding quote uses a TWAP/inference-based price that may differ.

SDK (@dimes-dot-fi/sdk):

Auth: User JWT

Request body:

Field
Required
Description

market_ticker

Yes

Market ticker.

effective_side

Yes

yes or no.

leverage_bps

Yes

Leverage in basis points (20000 = 2x).

notional_amount_usd_pips

Yes

Notional in USD pips.

entry_price_usd_pips

No

Effective-side entry price in USD pips. When omitted, the market's current reference price is used.

Response: 200 OK

Field
Description

estimated_liquidation_price_usd_pips

At-entry liquidation price estimate: entry * (L-1)/L * (1 + liquidation_fee_bps/10000). Estimate only.

expected_open_trading_fee_usdc_units

Venue trading fee to open (protocol venue fee + partner builder fee).

gross_max_gain_usdc_units

Profit on a win (settlement at $1) before fees: full token value minus notional. May be negative.

net_max_gain_usdc_units

gross_max_gain minus the open trading fee and origination fee. Excludes lifetime fees (upper bound). May be negative.

origination_fee_*

Combined origination fee (protocol tier + partner) at this leverage.

total_user_amount_usdc_units

Total the user must provide to open: collateral + open trading fee + origination fee.


Endpoint Summary

Method
Path
Auth
Description

GET

/v1/prediction-markets/markets

User JWT or API key

List/search markets

GET

/v1/prediction-markets/markets/{ticker}

User JWT or API key

Get market by ticker

GET

/v1/prediction-markets/events/{event_ticker}/markets

User JWT or API key

Markets for an event

GET

/v1/prediction-markets/series/{series_ticker}/markets

User JWT or API key

Markets for a series

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/positions/{position_id}/transactions

User JWT

Position transactions

GET

/v1/prediction-markets/markets/{ticker}/positions

User JWT

Positions on a market

GET

/v1/prediction-markets/events/{event_ticker}/positions

User JWT

Positions on an event

GET

/v1/prediction-markets/series/{series_ticker}/positions

User JWT

Positions in a series

GET

/v1/prediction-markets/partner-limits

Partner API key

Partner limits

GET

/v1/prediction-markets/user-limits

User JWT

User limits

GET

/v1/prediction-markets/fee-rates

User JWT

Fee schedule

POST

/v1/prediction-markets/fee-reports

User JWT

Cost & max-gain report

POST

/v1/prediction-markets/sample-events

User JWT or API key

Mock WebSocket events


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 1800 requests per minute per partner.

Exception: The POST /v1/prediction-markets/sample-events endpoint (mock WebSocket events) is throttled at one request every 30 seconds, per partner for API-key callers and per wallet for JWT callers. See Testing your integration.

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

Last updated