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

GET /prediction-markets/markets

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

const markets = await client.getMarkets({ limit: 25, sort: "depth_desc", expand: ["prices"] });
// markets.data: Market[]   markets.hasMore: boolean   markets.totalCount?: number

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

const results = await client.getMarkets({ query: "bitcoin", limit: 10 });

Response: 200 OK

{
  "data": [
    {
      "accepting_new_positions": true,
      "id": "dm_mkt_abc123",
      "ticker": "will-btc-hit-100k-2025",
      "polymarket": {
        "slug": "will-btc-hit-100k-2025",
        "condition_id": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
        "yes_token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
        "no_token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563"
      },
      "title": "Will BTC hit $100K?",
      "yes_sub_title": "Yes, before September 30",
      "category": "crypto",
      "rejection_reason_code": null,
      "sided_eligibility": {
        "yes": {
          "accepting_new_positions": true,
          "rejection_reason_code": null
        },
        "no": {
          "accepting_new_positions": false,
          "rejection_reason_code": "QUOTE_SIDE_CAPACITY_EXCEEDED"
        }
      },
      "status": "open",
      "tags": [
        "crypto",
        "bitcoin"
      ],
      "close_time": "2025-09-30T00:00:00.000Z",
      "discovered_at": "2025-09-01T08:00:00.000Z",
      "latest_enter_at": "2025-09-29T23:00:00.000Z",
      "provider": "polymarket",
      "min_collateral_usd_pips": "200000",
      "min_collateral_usd": "0.02",
      "min_notional_usd_pips": "10000",
      "min_notional_usd": "1.00",
      "leverage": {
        "min_bps": 20000,
        "max_yes_bps": 100000,
        "max_no_bps": 100000,
        "step_bps": 2500,
        "max_market_leverage_per_notional": {
          "yes": {
            "at100_usd_bps": 100000,
            "at500_usd_bps": 80000,
            "at1000_usd_bps": 60000,
            "at10000_usd_bps": 30000
          },
          "no": {
            "at100_usd_bps": 100000,
            "at500_usd_bps": 80000,
            "at1000_usd_bps": 60000,
            "at10000_usd_bps": 30000
          }
        }
      },
      "fees": {
        "origination_tiers": [
          {
            "max_leverage_bps": 40000,
            "fee_bps": 100
          },
          {
            "max_leverage_bps": 70000,
            "fee_bps": 125
          },
          {
            "max_leverage_bps": 100000,
            "fee_bps": 150
          }
        ],
        "lifetime_fee_apr_bps": 2000,
        "liquidation_fee_bps": 1000
      },
      "max_notional_yes_usd_pips": "500000000",
      "max_notional_yes_usd": "50000.00",
      "max_notional_no_usd_pips": "500000000",
      "max_notional_no_usd": "50000.00",
      "capacity_max_notional_yes_usd_pips": "400000000",
      "capacity_max_notional_yes_usd": "40000.00",
      "capacity_max_notional_no_usd_pips": "400000000",
      "capacity_max_notional_no_usd": "40000.00",
      "slippage_max_notional_yes_usd_pips": "350000000",
      "slippage_max_notional_yes_usd": "35000.00",
      "slippage_max_notional_no_usd_pips": "350000000",
      "slippage_max_notional_no_usd": "35000.00",
      "prices": {
        "yes_ask_price_usd": "0.51",
        "yes_ask_price_usd_pips": "5100",
        "yes_bid_price_usd": "0.49",
        "yes_bid_price_usd_pips": "4900",
        "no_ask_price_usd": "0.51",
        "no_ask_price_usd_pips": "5100",
        "no_bid_price_usd": "0.49",
        "no_bid_price_usd_pips": "4900"
      }
    }
  ],
  "has_more": true
}

Field reference:

Field	Type	Description
accepting_new_positions	boolean	Whether this market is currently accepting new positions on either side. See sided_eligibility for per-side breakdown.
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 (1000 = 10%)
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.
min_notional_usd	string	Minimum notional (dollar display)
min_notional_usd_pips	string	Minimum notional (internal precision)
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:

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

---

Get market

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

GET /prediction-markets/markets/{ticker}

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

const market = await client.getMarket("will-btc-hit-100k-2025");

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

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

const info = await client.getContractInfo();
// info.polygonVaultContractAddress, info.polygonUsdcTokenAddress, info.polygonSignerAddress

Auth: Public

Response: 200 OK

{
  "evm_chain_id": "137",
  "polygon_signer_address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
  "polygon_usdc_token_address": "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB",
  "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_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:

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

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

// You don't call this endpoint directly — the auth providers exchange your
// credentials for a JWT and refresh it automatically:
const client = new DimesClient({ auth: new ApiKeyAuth({ apiKey, walletAddress }) }); // server-side
// In the browser: new JwtAuth({ tokenUrl: "https://your-backend.com/api/dimes-token" })

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

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

// Recommended — executeQuote runs the full draft → promote flow with auto-correction:
const { quote, corrections } = await executeQuote(client, {
  marketTicker: "will-btc-hit-100k-2025",
  side: "yes",
  collateralUsd: 25,
  leverageBps: 50_000, // 5x
  slippageBps: 300,
});
// Low-level single call (params already finalized):
const direct = await client.createQuote(buildQuoteParams({
  marketTicker: "will-btc-hit-100k-2025", side: "yes", collateralUsd: 25, leverageBps: 50_000, slippageBps: 300,
}));

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.
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).
min_fill_bps	integer	no	Only valid with allow_partial_fill: true. Range 2000–5000, 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

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

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.

"max_gain": {
"gross_max_gain_usd": "138.46",
"gross_max_gain_usd_pips": "1384600",
"gross_max_gain_usdc_units": "138460000",
"net_max_gain_usd": "137.21",
"net_max_gain_usd_pips": "1372100",
"net_max_gain_usdc_units": "137210000"
}

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
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_usd_pips / _usd	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	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	Partner component in absolute terms (deprecated — prefer builder code fees)
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 offer 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	Protocol component in absolute terms
provider	polymarket
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".
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.
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	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.
wallet_address	Wallet address (from JWT)

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.

{
  "market_ticker": "will-btc-hit-100k-2025",
  "effective_side": "yes",
  "leverage_bps": 20000,
  "notional_usd_pips": "1000000000",
  "slippage_bps": 200,
  "allow_partial_fill": true,
  "min_fill_bps": 5000
}

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

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

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

const draft = await client.createDraftQuote(buildQuoteParams({
  marketTicker: "will-btc-hit-100k-2025", side: "yes", collateralUsd: 25, leverageBps: 50_000, slippageBps: 300,
}));

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.

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.

POST /prediction-markets/promoted-quotes/{draft_quote_id}

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

const quote = await client.promoteDraftQuote(draft.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

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

const positions = await client.getPositions({ status: "open" });
// positions: Position[] — narrow with isOpenPosition() / isClosedPosition()

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.
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,
      "close_attempt": 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,
        "initial_fill_bps": 9950,
        "origination_fee_bps": 125,
        "protocol_origination_fee_bps": 100,
        "partner_origination_fee_bps": 25,
        "origination_fee_usd_pips": "625000",
        "origination_fee_usd": "0.63",
        "opened_at": "2025-06-01T10:00:00.000Z",
        "open_latency_ms": 12500
      },
      "current": {
        "book_leverage_bps": 35000,
        "mark_price_usd_pips": "7000",
        "mark_price_usd": "0.70",
        "market_leverage_bps": 38500,
        "notional_usd_pips": "200000000",
        "notional_usd": "20000.00",
        "position_token_units": "384615",
        "remaining_bps": 7500,
        "collateral_usd_pips": "50000000",
        "collateral_usd": "50.00",
        "effective_collateral_usd_pips": "42000000",
        "effective_collateral_usd": "42.00",
        "unrealized_pnl_usd_pips": "-8000000",
        "unrealized_pnl_usd": "-8.00",
        "unrealized_pnl_bps": -1600,
        "net_unrealized_pnl_usd_pips": "-9200000",
        "net_unrealized_pnl_usd": "-9.20",
        "net_unrealized_pnl_bps": -1840,
        "position_value_usd_pips": "242000000",
        "position_value_usd": "24200.00"
      },
      "risk": {
        "health_bps": 7500,
        "current_liquidation_price_usd_pips": "3200",
        "current_liquidation_price_usd": "0.32",
        "liquidation_buffer_bps": 5077,
        "liquidation_fee_bps": 1000,
        "margin_buffer_usd_pips": "5000000",
        "margin_buffer_usd": "500.00"
      },
      "fees": {
        "lifetime_fee_apr_bps": 2000,
        "accrued_lifetime_fee_usd_pips": "1200000",
        "accrued_lifetime_fee_usd": "1.20",
        "pending_lifetime_fee_usd_pips": "300000",
        "pending_lifetime_fee_usd": "0.30",
        "accrued_venue_fee_usd_pips": "200000",
        "accrued_venue_fee_usd": "0.20",
        "total_fees_usd_pips": "2325000",
        "total_fees_usd": "2.33"
      },
      "timing": {
        "is_settlement_pending": false,
        "is_voided": false,
        "market_close_time": "2025-09-30T00:00:00.000Z",
        "market_status": "active",
        "time_to_close_minutes": 172800
      }
    }
  ],
  "has_more": false
}

Open position field reference:

Field	Description
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 offer'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 — does not change when the position is partially closed. Use this for an "opened at X% of requested" indicator. null until the open fill is recorded.
entry.leverage_bps	Entry leverage (50000 = 5x)
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 on the offer
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 (1000 = 10%)
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.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",
  "revert_reason": 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",
    "origination_fee_bps": 125,
    "protocol_origination_fee_bps": 100,
    "partner_origination_fee_bps": 25,
    "origination_fee_usd_pips": "625000",
    "origination_fee_usd": "0.63",
    "opened_at": "2025-06-01T10:00:00.000Z",
    "open_latency_ms": 12500
  },
  "result": {
    "closed_at": "2025-07-15T14:30:00.000Z",
    "realized_pnl_usd_pips": "15000000",
    "realized_pnl_usd": "15.00",
    "net_realized_pnl_usd_pips": "13375000",
    "net_realized_pnl_usd": "13.38",
    "net_realized_pnl_bps": 2675,
    "proceeds_usd_pips": "65000000",
    "proceeds_usd": "65.00",
    "exit_notional_usd_pips": "78000000",
    "exit_notional_usd": "78.00",
    "collected_lifetime_fee_usd_pips": "1500000",
    "collected_lifetime_fee_usd": "1.50",
    "collected_liquidation_fee_usd_pips": "0",
    "collected_liquidation_fee_usd": "0.00"
  },
  "fees": {
    "lifetime_fee_apr_bps": 2000,
    "total_lifetime_fee_usd_pips": "1500000",
    "total_lifetime_fee_usd": "1.50",
    "total_venue_fee_usd_pips": "200000",
    "total_venue_fee_usd": "0.20",
    "total_fees_usd_pips": "2325000",
    "total_fees_usd": "2.33"
  }
}

Deprecated fields on closed fees: origination_fee_bps, protocol_origination_fee_bps, partner_origination_fee_bps, origination_fee_usd_pips, origination_fee_usd are still emitted for backwards compatibility but duplicate the canonical values on entry.*. New integrations should read the origination fields from entry only.

Field	Description
close_reason	closed, settled, liquidated, cancelled, or reverted
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).

GET /prediction-markets/positions/{position_id}

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

// No dedicated single-position method — filter from getPositions():
const position = (await client.getPositions()).find((p) => p.id === positionId);

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,
            "reason": "spread_blowout",
            "reason_detail": "The bid-ask spread widened sharply beyond its recent baseline, signalling thinning liquidity."
          }
        ],
        "has_more": false
      }
    }
  ],
  "has_more": true
}

Field reference (each unwind event):

Field	Type	Description
after_leverage_bps	integer	Leverage after unwind in basis points (20000 = 2x)
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
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.

---

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.

GET /prediction-markets/positions/{position_id}/transactions

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

const transactions = await client.getPositionTransactions(positionId);

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

Response: 200 OK

{
  "open": {
    "transactions": [
      {
        "transaction_hash": "0xffe5e3d042e9bf100fd01ad7a8d4de5d7fd20632df62e319d50275673e42e410",
        "exchange_transaction_hashes": [
          "0xddc31a8f7d2e4c0b9a1e5f3c8b6d4a2e0f9c7b5a3d1e8f6c4b2a0d9e7f5c3b1a"
        ]
      },
      {
        "transaction_hash": "0xaa11bb22cc33dd44ee55ff6677889900aabbccddeeff00112233445566778899"
      }
    ]
  },
  "close": {
    "transactions": []
  },
  "liquidation": {
    "transactions": []
  },
  "settle": {
    "transactions": []
  },
  "force_unwind": {
    "transactions": []
  },
  "cancel_request": {
    "transactions": []
  },
  "cancel": {
    "transactions": []
  },
  "revert": {
    "transactions": []
  },
  "redemption": {
    "transactions": []
  }
}

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)

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.

GET /prediction-markets/positions/{position_id}/partial-closes

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

const partialCloses = await client.getPositionPartialCloses(positionId);

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

Response: 200 OK

{
  "data": [
    {
      "executed_at": "2026-07-01T14:59:28.000Z",
      "sold_token_units": "94590000",
      "average_sale_price_usd_pips": "2838",
      "average_sale_price_usd": "0.28",
      "sale_proceeds_usd_pips": "268468",
      "sale_proceeds_usd": "26.85",
      "capital_repaid_usd_pips": "144859",
      "capital_repaid_usd": "14.49",
      "user_payout_usd_pips": "123608",
      "user_payout_usd": "12.36",
      "remaining_position_token_units": "220720000",
      "new_leverage_bps": 19999
    }
  ],
  "has_more": false
}

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
404	customer_position_not_found

---

5. Limits

Partner limits

Partner's global position limit and current usage.

GET /prediction-markets/partner-limits

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

const limits = await client.getPartnerLimits();

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

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

const limits = await client.getUserLimits();

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

GET /prediction-markets/fee-rates

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

const feeRates = await client.getFeeRates({ ticker: "will-btc-hit-100k-2025" });

Auth: User JWT

Query parameters:

Parameter	Required	Description
ticker	No	Market ticker. When set, the response includes market.

Response: 200 OK

{
  "contract_max_origination_fee_bps": 1000,
  "lifetime_fee_apr_bps": 2000,
  "liquidation_fee_bps": 250,
  "origination_fee_tiers": [
    {
      "fee_bps": 200,
      "max_leverage_bps": 40000
    },
    {
      "fee_bps": 225,
      "max_leverage_bps": 70000
    },
    {
      "fee_bps": 250,
      "max_leverage_bps": 100000
    }
  ],
  "partner_origination_fee_bps": 0,
  "partner_trading_fee_bps": 0,
  "market": {
    "polymarket_fee_exponent": 1,
    "polymarket_trading_fee_bps": 0,
    "ticker": "TRUMP-2024-WIN"
  }
}

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.

POST /prediction-markets/fee-reports

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

const report = await client.getFeeReport({ /* FeeReportParams: date range + filters */ });

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

{
  "collateral_usdc_units": "25000000",
  "effective_side": "yes",
  "entry_price_usd_pips": "5100",
  "estimated_liquidation_price_usd_pips": "2613",
  "expected_open_trading_fee_usdc_units": "0",
  "gross_max_gain_usdc_units": "48039215",
  "leverage_bps": 20000,
  "market_ticker": "TRUMP-2024-WIN",
  "net_max_gain_usdc_units": "47039215",
  "notional_amount_usd_pips": "500000",
  "notional_usdc_units": "50000000",
  "origination_fee_bps": 200,
  "origination_fee_usdc_units": "1000000",
  "partner_origination_fee_bps": 0,
  "partner_trading_fee_bps": 0,
  "polymarket_trading_fee_bps": 0,
  "protocol_origination_fee_bps": 200,
  "total_user_amount_usdc_units": "26000000"
}

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

---

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.

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