Configs

The configs query returns all coin definitions and contract configurations available on the exchange. Use it to resolve contract IDs for the a field, read the decimal scales that convert display values to the raw integers the wire protocol expects, obtain tick and step sizes for validation, and inspect leverage tiers for margin calculations.

This endpoint is the authority

Three sources describe the API, and they are not interchangeable:

Source	Defines	Never use it for
The endpoint reference pages	Structure — field names, types, required/optional, enum sets	Current parameter values
`configs` (this endpoint)	Current trading parameters — scales, tick/step, leverage, tiers, fees, limits	—
Examples anywhere in these docs	Nothing. They illustrate shape only	Any business fact: scales, IDs, contract names, leverage, fees

Every numeric value in every example on this site is illustrative and must not be used to build an order. Resolve the real value from configs at runtime, for the exact contract you are trading.

Scales are per contract and are frequently 0. A contract with priceScale: 0 takes the display price unchanged; one with qtyScale: 0 takes whole units only. Reusing another contract’s scale, or a scale copied from documentation, misprices an order by a factor of ten or more without any error from the server. Read priceScale and qtyScale from the contract object you are about to trade — every session, never cached across a config change.

Stop conditions

An automated client must halt and surface the problem rather than improvise when any of the following holds. Substituting a different contract is never correct.

The target contract name is absent from the response.
More than one contract shares the target name.
The contract object is missing any field the order path needs: priceScale, qtyScale, tickSize, stepSize, notionalScaleMultiplier, or tiers.
The matched contract’s status is anything other than "Active".

There is no version or snapshot identifier on this response. You cannot currently prove that a quote, a validation pass, and a signature all used the same configuration. The only change signal available is the version field pushed by the config WebSocket channel — subscribe to it, and re-fetch configs and re-validate any unsigned order when the version changes. Treat a configuration change between validation and signing as a reason to abort and revalidate.

Request

{"type": "configs", "marketDeployerId": 0}

string

required

type (required) — Must be "configs".

integer

marketDeployerId — Filter contracts by Market Deployer. Use 0 or omit to return configuration for all deployers. Pass a positive integer to restrict results to a specific deployer.

Response

{
  "type": "configs",
  "marketDeployerIdFilter": 0,
  "coins": [
    { "coinId": 1, "name": "USDC", "szDecimals": 6, "isMargin": true, "status": "Active" },
    { "coinId": 3, "name": "BTC", "szDecimals": 8, "isMargin": false, "status": "Active" }
  ],
  "contracts": [
    {
      "contractId": 1,
      "marketId": 1,
      "marketDeployerId": 1,
      "name": "BTC-USDC",
      "baseCoinId": 3,
      "quoteCoinId": 1,
      "tickSize": "1",
      "stepSize": "1",
      "priceScale": 0,
      "qtyScale": 4,
      "notionalScaleMultiplier": "100",
      "flags": 0,
      "listingTime": 0,
      "priceBandBps": 100,
      "liquidationFee": 0,
      "defaultTakerFee": 0,
      "defaultMakerFee": null,
      "defaultLeverage": "20",
      "fundingInterval": 3600,
      "maxOrderSize": "0",
      "maxPositionSize": "0",
      "fundingInterestRate": "0",
      "fundingMaxValue": "0",
      "fundingMaxRate": "0",
      "fundingMinRate": "0",
      "markPriceVarRate": "0",
      "openPrice": "0",
      "contractType": 1,
      "status": "Active",
      "icon": "",
      "digitMerge": ["1", "10", "100"],
      "descKey": "",
      "label": "",
      "liquidatorAccountId": "0",
      "openPositionOiLimitRate": "0",
      "shortName": "Bitcoin",
      "partialLiquidationNotionalThreshold": "0",
      "tiers": [
        { "upperBound": "2000000000000", "maxLeverage": "40", "imBps": 250, "mmBps": 125 },
        { "upperBound": "9223372036854775807", "maxLeverage": "10", "imBps": 1000, "mmBps": 500 }
      ]
    },
    {
      "contractId": 3,
      "name": "EXAMPLE-USDC",
      "priceScale": 2,
      "qtyScale": 2,
      "status": "Delisted"
    }
  ],
  "chainFeeAccountId": "0",
  "chainFeeShare": 0,
  "feePrecision": 100000,
  "minNotionalValue": "1000000",
  "marketSlippageBps": 800,
  "tpslMarketSlippageBps": 1000,
  "allIsMarginCoins": [1],
  "shareMarginGroups": [],
  "marketDeployers": [
    {
      "marketDeployerId": 1,
      "deployerAccountId": "10",
      "liquidatorAccountId": "11",
      "deployerTakerFee": null,
      "deployerMakerFee": null,
      "settleCoinId": 1
    }
  ]
}

The response mixes tradeable and untradeable contracts. The second entry above is Delisted and is shortened here for space; the server returns it in full, with a complete and plausible set of parameters, and nothing else marks it as unusable. Filter on status before anything else.Note also that priceScale is 0 for the first contract: its raw price equals its display price. Scales differ per contract and 0 is common.

All values in the example illustrate shape only. Read every parameter from the live response.

Discovery and filtering

string

Contract status:

"Active" — the contract is tradeable.
"Frozen" — the contract is hidden.
"Delisted" — the contract is delisted. Delisting is irreversible.

Treat any value other than "Active" as untradeable. configs does not filter by status: frozen and delisted contracts are returned with a complete parameter set and are indistinguishable from a live one on any other field.

Coin status is independent of contract status. Coins carry the same three status values, and a coin can stay Active after its contract is delisted, so a coin being Active tells you nothing about whether you can trade it. Always check the contract.

Resolve a contract in this order:

Filter to status Active

Discard every contract whose status is not exactly "Active".

Match on name

Find your target by name. Never select by contractId — IDs are server-assigned and do not map to any fixed pair.

Stop if the result is not exactly one contract

Zero matches, or more than one, is a stop condition. Do not fall back to another contract.

Read that contract's own parameters

Take priceScale, qtyScale, tickSize, stepSize and tiers from the matched object only.

Fee defaults

Fee-rate fields are scaled by 1e5: the applied rate is the field value divided by the top-level feePrecision. The price band, margin and slippage fields (priceBandBps, imBps, mmBps, marketSlippageBps, tpslMarketSlippageBps) and openPositionOiLimitRate are scaled by 1e4, and the funding-rate fields by 1e8. Do not mix the scales.

integer | null

Contract-level default taker fee rate, scaled by 1e5. null means not set. A negative value is a rebate. The rate actually applied to your account resolves through the fee hierarchy — read effectiveTakerFee from userAccount for the value in force.

integer | null

Contract-level default maker fee rate, scaled by 1e5, with the same null and sign rules as defaultTakerFee.

integer

Liquidation fee rate, scaled by 1e5.

Notional, and the limits enforced on it

Order validation works on notional value, not on price or size alone. Notional value is an integer in the settlement coin’s raw units — the quote coin’s szDecimals — and is computed from the raw price and raw quantity:

notional = price × size × notionalScaleMultiplier      (all raw integers)

string

The conversion factor from raw price and raw quantity to notional value in the settlement coin’s raw units (raw integer string). Read it from this response rather than recomputing it.

string

Top-level field. Minimum order notional value, in settlement-coin raw units, applied globally. A non-reduce-only order whose notional value is below it is rejected. "0" means no minimum.

string

Maximum quantity of a single order (raw, scaled by qtyScale). "0" means no limit. Applies to every non-reduce-only order.

string

Maximum position quantity on this contract (raw, scaled by qtyScale). "0" means no limit. It is checked against the existing position plus the new order, and blocks only orders that increase exposure; closing orders are exempt, including an opposite-side order without reduceOnly.

string

Cap on one account’s exposure as a share of the contract’s open interest, scaled by 1e4. "0" means no limit. The effective cap is max(maxPositionSize, openInterest × openPositionOiLimitRate / 1e4), where open interest is the total size of all positions on the contract, long and short combined, and exposure is the existing position plus non-reduce-only open orders plus the new order.

integer

Price band around the mark price, scaled by 1e4. The band constrains only the aggressive direction: a limit buy priced above the mark price, or a limit sell priced below it, is rejected when it deviates from the mark price by more than the band. A buy below the mark price or a sell above it is not constrained. Order modifications follow the same rule. 0 means the band is not set; 32767 explicitly disables it.

Compute a market order’s price yourself and validate it before signing. Derive it from the mark price and your account’s marketSlippageBps from userAccount. A mistyped price can sweep the book.

Other contract fields

integer

Market ID; currently equal to contractId.

integer

The Market Deployer the contract belongs to.

integer

The underlying coin of the contract, matching coins[].coinId.

integer

The quote and settlement coin, matching coins[].coinId. Prices, margin, PnL and fees on this contract are all denominated in it, and amounts use its szDecimals.

integer

Contract flag bitmask. Reserved.

integer

Trading start time in Unix milliseconds. 0 means not set or already open. Before this time, non-reduce-only orders are rejected; reduce-only orders and liquidations are not affected.

string

Opening price for display (raw, scaled by priceScale). "0" means not set.

integer

Contract type: 1 crypto, 2 stock.

string[]

Order book price aggregation levels, as raw integer strings in ascending order, each a multiple of tickSize. An empty array means none are configured. Pass one of these values as group to l2Book. The values are raw integers; convert them with priceScale for display.

string

Display name of the underlying coin, such as "Bitcoin". It is a different dimension from name, which is the contract name. Display only. "" when not set.

string

Category label for grouping contracts in a display. "" when not set.

string

Key of the coin description text. "" when not set.

string

Liquidation account specific to this contract. "0" means not set; the Market Deployer’s liquidation account applies.

string

Notional value threshold for partial liquidation, in settlement-coin raw units on the same basis as size × mark price. A position whose notional value is above the threshold is liquidated partially; at or below it, in full. "0" means not set, and a global default applies.

string

Interest-rate component of the funding rate (raw, scaled by 1e8).

string

Upper bound of the funding rate (raw, scaled by 1e8).

string

Lower bound of the funding rate (raw, scaled by 1e8). Can be negative.

string

Maximum notional value used to probe order book depth when computing the premium index (raw, in the settlement coin). It is not a cap on a single funding payment.

string

Allowed variation rate of the mark price (raw, scaled by 1e8).

Top-level fields

string

Always "configs".

integer

The marketDeployerId filter from the request; 0 means all Market Deployers.

object[]

Coin definitions: {coinId, name, szDecimals, isMargin, status}. szDecimals is the coin’s decimal places for amounts; isMargin is true when the coin can be used as margin and false otherwise; status is "Active", "Frozen", or "Delisted".

object[]

Contract definitions, with the fields described on this page.

integer

Denominator of every fee-rate field in this response, always 100000. It applies to chainFeeShare, defaultTakerFee, defaultMakerFee, liquidationFee, deployerTakerFee and deployerMakerFee. It does not apply to the fields scaled by 1e4 or 1e8.

integer

Global market-order slippage cap, scaled by 1e4.

integer

Global slippage cap for take-profit and stop-loss market orders, scaled by 1e4. Use it to compute the execution price of a TP/SL market order.

string

Chain-level fee account. "0" means not set.

Chain-level fee share, scaled by 1e5.

integer[]

IDs of all coins usable as margin — the coins with isMargin set to true.

Share group definitions: {groupId, settleCoinId, status, contractIds}. The same definitions are returned by shareGroupState.

object[]

Registered Market Deployers:

marketDeployerId (integer) — the Market Deployer ID.
deployerAccountId (string) — the Market Deployer’s account.
liquidatorAccountId (string) — the Market Deployer’s liquidation account.
deployerTakerFee, deployerMakerFee (integer or null) — the Market Deployer’s fee rates, scaled by 1e5; null when not set.
settleCoinId (integer) — the Market Deployer’s settlement coin.

marketSlippageBps exists at two different scopes with the same name. The one in this response is a global setting. The one returned by userAccount, and written by updateSlippageSetting, is an account setting scoped to (account, Market Deployer) and is the one that governs the price you compute for a market order. Do not substitute one for the other.

Treat any field not described on this page as reserved. A future response may add fields; ignore unknown keys rather than failing, and do not rely on a field’s continued presence until it is specified here.

Contract Fields

integer

The unique contract identifier. Use this as the a field when placing, modifying, or canceling orders.

string

Human-readable contract name (e.g. "BTC-USDC").

string

Minimum price movement expressed as a raw integer string. All order prices must be multiples of this value.

string

Minimum quantity movement expressed as a raw integer string. All order quantities must be multiples of this value.

integer

Decimal exponent for prices. Divide any raw price by 10^priceScale to get the human-readable display value.

integer

Decimal exponent for quantities. Divide any raw quantity by 10^qtyScale to get the human-readable display value.

string

The contract’s default leverage. It applies when the account has not set leverage for the contract (contractSettings[].leverage of "0" in userAccount).

string

URL of the contract’s icon, or an empty string when none is set — never null. The host is not guaranteed and varies between contracts, so treat the value as an opaque URL: do not derive other URLs from it, and do not assume it is served from an UpsideMAX domain.

integer

Funding settlement interval in seconds; funding settles once per interval. The value comes from a fixed set: 3600 (1h), 7200 (2h), 14400 (4h), or 28800 (8h).

Tier[]

Leverage tier schedule for this contract, in ascending upperBound order. A position uses the first tier whose upperBound is greater than or equal to the position’s notional value. The number of tiers is the array length.

Show Tier fields

string

Upper bound of the position notional value covered by this tier (raw, in the settlement coin’s units). The last tier always uses "9223372036854775807" (max int64), so it covers any position size.

string

Maximum leverage allowed in this tier. The leverage you set is capped at the maxLeverage of the tier your position is in.

integer

Initial margin rate, scaled by 1e4. It equals ceil(1e4 / maxLeverage).

integer

Maintenance margin rate, scaled by 1e4, never greater than imBps. Positions are liquidated when equity falls below the maintenance margin.

Overview

Market Data

Account

Orders

History

This endpoint is the authority

Stop conditions

Request

Response

Discovery and filtering

Fee defaults

Notional, and the limits enforced on it

Other contract fields

Top-level fields

Contract Fields

​This endpoint is the authority

​Stop conditions

​Request

​Response

​Discovery and filtering

​Fee defaults

​Notional, and the limits enforced on it

​Other contract fields

​Top-level fields

​Contract Fields

This endpoint is the authority

Stop conditions

Request

Response

Discovery and filtering

Fee defaults

Notional, and the limits enforced on it

Other contract fields

Top-level fields

Contract Fields