# Get market by id

`GET /v2/markets/{id}`

One market with the same snapshot the list returns.

Responds `404` when the market does not exist, is delisted, or is hidden from the caller.

## Authorization

bearer: http · bearer (required). Personal API key, prefixed with `usk_`.

## Parameters

- path: id (string · uuid; required). Market identifier, as returned by `GET /v2/markets`.

Type: string · uuid

format: uuid

- query: accountId (string · uuid; optional). Trader account to resolve the market list against: leverage bounds and availability are returned as they apply to that account. Omitted — the platform-wide defaults are returned.

Type: string · uuid

format: uuid

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

## Example · cURL

```bash
curl --request GET 'https://api.upscale.trade/v2/markets/{id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Example · JavaScript

```javascript
const response = await fetch("https://api.upscale.trade/v2/markets/{id}", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
});
console.log(response.status, await response.text());
```

## Example · Python

```python
import requests

response = requests.request(
    "GET",
    "https://api.upscale.trade/v2/markets/{id}",
    headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
print(response.status_code, response.text)
```

## Response 401

**401**  — Unauthorized

## Response 404

**404**  — Market not found, delisted, or hidden from the caller.

## Response 429

**429**  — Rate limit of the API key exceeded (`api_key_rate_limit_exceeded`). `Retry-After` says when to come back; the body carries the bucket (`read` / `write`), the window that tripped, its limit and `retryAt`.

## Response default · MarketV2Response

**default** application/json — Response

Schema: MarketV2Response

Type: object

Required fields: id, config, state, settings, change, schedule

Required field types: id (string · uuid; required), config (object; required), state (object; required), settings (object; required), change (object; required), schedule (object · nullable; required)

- id (string · uuid; required)

id example: 00000000-0000-4000-8000-000000000000

id.Type: string · uuid

id.Market identifier — the value order creation takes as `marketId`.

id.format: uuid

id.pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

- config (object; required)

config example: {
  "baseAsset": "BTC",
  "quoteAsset": "USD",
  "settlementToken": "USD",
  "type": "base",
  "name": "BTC",
  "description": "Market description",
  "ticker": "BTC/USD",
  "imageLink": "https://app.storm.tg/markets/btc.png",
  "tags": [
    "Crypto"
  ],
  "category": "crypto",
  "priority": 0
}

config.Type: object

config.Required fields: baseAsset, quoteAsset, settlementToken, type, name, description, ticker, imageLink, tags, category, priority

config.Required field types: baseAsset (string; required), quoteAsset (string; required), settlementToken (string; required), type (string; required), name (string; required), description (string; required), ticker (string; required), imageLink (string; required), tags (string[]; required), category (string · enum; required), priority (number · nullable; required)

config.Static description of the market: assets, naming and category.

- config.baseAsset (string; required)

config.baseAsset example: BTC

config.baseAsset.Type: string

config.baseAsset.Base asset ticker — the value the per-market endpoints take as `asset`.

- config.quoteAsset (string; required)

config.quoteAsset example: USD

config.quoteAsset.Type: string

config.quoteAsset.Asset prices and notionals are quoted in.

- config.settlementToken (string; required)

config.settlementToken example: USD

config.settlementToken.Type: string

config.settlementToken.Asset positions settle in.

- config.type (string; required)

config.type example: base

config.type.Type: string

config.type.Pricing model of the market.

- config.name (string; required)

config.name example: BTC

config.name.Type: string

config.name.Display name of the market.

- config.description (string; required)

config.description example: Market description

config.description.Type: string

config.description.Free-form description shown in the app.

- config.ticker (string; required)

config.ticker example: BTC/USD

config.ticker.Type: string

config.ticker.Full pair label.

- config.imageLink (string; required)

config.imageLink example: https://app.storm.tg/markets/btc.png

config.imageLink.Type: string

config.imageLink.Icon of the market.

- config.tags (string[]; required)

config.tags example: [
  "Crypto"
]

config.tags.Type: string[]

config.tags.Tags the app groups markets by.

config.tags.[]Type: string

- config.category (string · enum; required)

config.category example: crypto

config.category.Type: string · enum

config.category.Whether the market is crypto or a real-world asset — an account may be limited to one of the two.

config.category.Allowed values: ["crypto","rwa"]

- config.priority (number · nullable; required)

config.priority example: 0

config.priority.Type: number · nullable

config.priority.Sort weight in the market list; higher comes first. Null when unranked.

- state (object; required)

state example: {
  "indexPrice": "1000000000",
  "blockTimestamp": 0,
  "fundingRate": "1000000000",
  "nextFundingAt": 0,
  "lastFundingAt": 0,
  "vpiSpread": "1000000000",
  "vpiMarketDepthLong": "1000000000",
  "vpiMarketDepthShort": "1000000000",
  "vpiCoefficientLong": "1000000000",
  "vpiCoefficientShort": "1000000000"
}

state.Type: object

state.Required fields: indexPrice, blockTimestamp, fundingRate, nextFundingAt, lastFundingAt, vpiSpread, vpiMarketDepthLong, vpiMarketDepthShort, vpiCoefficientLong, vpiCoefficientShort

state.Required field types: indexPrice (string · int32; required), blockTimestamp (number; required), fundingRate (string · int32; required), nextFundingAt (number; required), lastFundingAt (number · nullable; required), vpiSpread (string · int32; required), vpiMarketDepthLong (string · int32; required), vpiMarketDepthShort (string · int32; required), vpiCoefficientLong (string · int32; required), vpiCoefficientShort (string · int32; required)

state.Live state: index price, funding and the depth an order is priced against.

- state.indexPrice (string · int32; required)

state.indexPrice example: 1000000000

state.indexPrice.Type: string · int32

state.indexPrice.Current index price of the market, fp9 raw — what orders are priced and triggers compared against.

state.indexPrice.format: int32

state.indexPrice.pattern: ^(?:-?[1-9][0-9]*|0)$

- state.blockTimestamp (number; required)

state.blockTimestamp example: 0

state.blockTimestamp.Type: number

state.blockTimestamp.When this state snapshot was produced, unix timestamp in milliseconds.

- state.fundingRate (string · int32; required)

state.fundingRate example: 1000000000

state.fundingRate.Type: string · int32

state.fundingRate.Funding rate of the running interval, fp9 raw fraction. Positive means longs pay shorts.

state.fundingRate.format: int32

state.fundingRate.pattern: ^(?:-?[1-9][0-9]*|0)$

- state.nextFundingAt (number; required)

state.nextFundingAt example: 0

state.nextFundingAt.Type: number

state.nextFundingAt.When funding is settled next, unix timestamp in milliseconds.

- state.lastFundingAt (number · nullable; required)

state.lastFundingAt example: 0

state.lastFundingAt.Type: number · nullable

state.lastFundingAt.When funding was last settled, unix timestamp in milliseconds. Null before the first settlement.

- state.vpiSpread (string · int32; required)

state.vpiSpread example: 1000000000

state.vpiSpread.Type: string · int32

state.vpiSpread.Current spread charged on top of the index price, fp9 raw fraction.

state.vpiSpread.format: int32

state.vpiSpread.pattern: ^(?:-?[1-9][0-9]*|0)$

- state.vpiMarketDepthLong (string · int32; required)

state.vpiMarketDepthLong example: 1000000000

state.vpiMarketDepthLong.Type: string · int32

state.vpiMarketDepthLong.Depth available on the long side, fp9 raw. Orders large against it move the execution price.

state.vpiMarketDepthLong.format: int32

state.vpiMarketDepthLong.pattern: ^(?:-?[1-9][0-9]*|0)$

- state.vpiMarketDepthShort (string · int32; required)

state.vpiMarketDepthShort example: 1000000000

state.vpiMarketDepthShort.Type: string · int32

state.vpiMarketDepthShort.Depth available on the short side, fp9 raw.

state.vpiMarketDepthShort.format: int32

state.vpiMarketDepthShort.pattern: ^(?:-?[1-9][0-9]*|0)$

- state.vpiCoefficientLong (string · int32; required)

state.vpiCoefficientLong example: 1000000000

state.vpiCoefficientLong.Type: string · int32

state.vpiCoefficientLong.Price-impact coefficient applied to long orders, fp9 raw.

state.vpiCoefficientLong.format: int32

state.vpiCoefficientLong.pattern: ^(?:-?[1-9][0-9]*|0)$

- state.vpiCoefficientShort (string · int32; required)

state.vpiCoefficientShort example: 1000000000

state.vpiCoefficientShort.Type: string · int32

state.vpiCoefficientShort.Price-impact coefficient applied to short orders, fp9 raw.

state.vpiCoefficientShort.format: int32

state.vpiCoefficientShort.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings (object; required)

settings example: {
  "fee": "1000000000",
  "minInitMarginRatio": "1000000000",
  "initMarginRatio": "1000000000",
  "maintenanceMarginRatio": "1000000000",
  "maxLeverageByAccount": {
    "key": "1000000000"
  },
  "spreadLimit": "1000000000",
  "maxPriceImpact": "1000000000",
  "maxPriceSpread": "1000000000",
  "maxOpenNotionalLong": "1000000000",
  "maxOpenNotionalShort": "1000000000",
  "minStopTriggerDistanceRatio": "1000000000",
  "isCloseOnly": true,
  "isClosed": true,
  "isPaused": true,
  "isZeroSpread": true
}

settings.Type: object

settings.Required fields: fee, minInitMarginRatio, initMarginRatio, maintenanceMarginRatio, maxLeverageByAccount, spreadLimit, maxPriceImpact, maxPriceSpread, maxOpenNotionalLong, maxOpenNotionalShort, minStopTriggerDistanceRatio, isCloseOnly, isClosed, isPaused, isZeroSpread

settings.Required field types: fee (string · int32; required), minInitMarginRatio (string · int32; required), initMarginRatio (string · int32; required), maintenanceMarginRatio (string · int32; required), maxLeverageByAccount (object; required), spreadLimit (string · int32; required), maxPriceImpact (string · int32; required), maxPriceSpread (string · int32; required), maxOpenNotionalLong (string · int32; required), maxOpenNotionalShort (string · int32; required), minStopTriggerDistanceRatio (string · int32; required), isCloseOnly (boolean; required), isClosed (boolean; required), isPaused (boolean; required), isZeroSpread (boolean; required)

settings.Trading rules of the market: fees, margin ratios and the caps an order is checked against.

- settings.fee (string · int32; required)

settings.fee example: 1000000000

settings.fee.Type: string · int32

settings.fee.Trading fee rate, fp9 raw fraction (`1000000` = 0.1%).

settings.fee.format: int32

settings.fee.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.minInitMarginRatio (string · int32; required)

settings.minInitMarginRatio example: 1000000000

settings.minInitMarginRatio.Type: string · int32

settings.minInitMarginRatio.Smallest initial margin ratio the market accepts, fp9 raw fraction — the cap on leverage.

settings.minInitMarginRatio.format: int32

settings.minInitMarginRatio.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.initMarginRatio (string · int32; required)

settings.initMarginRatio example: 1000000000

settings.initMarginRatio.Type: string · int32

settings.initMarginRatio.Default initial margin ratio of the market, fp9 raw fraction.

settings.initMarginRatio.format: int32

settings.initMarginRatio.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.maintenanceMarginRatio (string · int32; required)

settings.maintenanceMarginRatio example: 1000000000

settings.maintenanceMarginRatio.Type: string · int32

settings.maintenanceMarginRatio.Margin ratio below which a position is liquidated, fp9 raw fraction.

settings.maintenanceMarginRatio.format: int32

settings.maintenanceMarginRatio.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.maxLeverageByAccount (object; required)

settings.maxLeverageByAccount example: {
  "key": "1000000000"
}

settings.maxLeverageByAccount.Type: object

settings.maxLeverageByAccount.Highest leverage allowed per account type, fp9 raw, keyed by account type.

settings.maxLeverageByAccount.*.Type: string · int32

settings.maxLeverageByAccount.*.Example: "1000000000"

settings.maxLeverageByAccount.*.format: int32

settings.maxLeverageByAccount.*.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.spreadLimit (string · int32; required)

settings.spreadLimit example: 1000000000

settings.spreadLimit.Type: string · int32

settings.spreadLimit.Largest spread the market will charge, fp9 raw fraction.

settings.spreadLimit.format: int32

settings.spreadLimit.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.maxPriceImpact (string · int32; required)

settings.maxPriceImpact example: 1000000000

settings.maxPriceImpact.Type: string · int32

settings.maxPriceImpact.Largest price impact a single order may cause, fp9 raw fraction.

settings.maxPriceImpact.format: int32

settings.maxPriceImpact.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.maxPriceSpread (string · int32; required)

settings.maxPriceSpread example: 1000000000

settings.maxPriceSpread.Type: string · int32

settings.maxPriceSpread.Largest deviation allowed between market and index price, fp9 raw fraction.

settings.maxPriceSpread.format: int32

settings.maxPriceSpread.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.maxOpenNotionalLong (string · int32; required)

settings.maxOpenNotionalLong example: 1000000000

settings.maxOpenNotionalLong.Type: string · int32

settings.maxOpenNotionalLong.Cap on open notional held long on this market, fp9 raw. `0` means no cap.

settings.maxOpenNotionalLong.format: int32

settings.maxOpenNotionalLong.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.maxOpenNotionalShort (string · int32; required)

settings.maxOpenNotionalShort example: 1000000000

settings.maxOpenNotionalShort.Type: string · int32

settings.maxOpenNotionalShort.Cap on open notional held short on this market, fp9 raw. `0` means no cap.

settings.maxOpenNotionalShort.format: int32

settings.maxOpenNotionalShort.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.minStopTriggerDistanceRatio (string · int32; required)

settings.minStopTriggerDistanceRatio example: 1000000000

settings.minStopTriggerDistanceRatio.Type: string · int32

settings.minStopTriggerDistanceRatio.Minimum distance between the current price and a stop trigger, fp9 raw fraction. A closer trigger is pushed out to this distance.

settings.minStopTriggerDistanceRatio.format: int32

settings.minStopTriggerDistanceRatio.pattern: ^(?:-?[1-9][0-9]*|0)$

- settings.isCloseOnly (boolean; required)

settings.isCloseOnly example: true

settings.isCloseOnly.Type: boolean

settings.isCloseOnly.Whether the market only accepts orders that close a position.

- settings.isClosed (boolean; required)

settings.isClosed example: true

settings.isClosed.Type: boolean

- settings.isPaused (boolean; required)

settings.isPaused example: true

settings.isPaused.Type: boolean

- settings.isZeroSpread (boolean; required)

settings.isZeroSpread example: true

settings.isZeroSpread.Type: boolean

settings.isZeroSpread.Whether the market currently trades without a spread.

- change (object; required)

change example: {
  "initialPrice": 0,
  "initialPrice1h": 0,
  "initialPrice4h": 0
}

change.Type: object

change.Required fields: initialPrice, initialPrice1h, initialPrice4h

change.Required field types: initialPrice (number; required), initialPrice1h (number; required), initialPrice4h (number; required)

change.Reference prices for computing 1h, 4h and 24h price changes.

- change.initialPrice (number; required)

change.initialPrice example: 0

change.initialPrice.Type: number

change.initialPrice.Price 24 hours ago, as a decimal number — the base of the daily change. `0` when no history is available.

- change.initialPrice1h (number; required)

change.initialPrice1h example: 0

change.initialPrice1h.Type: number

change.initialPrice1h.Price one hour ago, as a decimal number. `0` when no history is available.

- change.initialPrice4h (number; required)

change.initialPrice4h example: 0

change.initialPrice4h.Type: number

change.initialPrice4h.Price four hours ago, as a decimal number. `0` when no history is available.

- schedule (object · nullable; required)

schedule example: {
  "nextPauseAt": 0,
  "nextUnpauseAt": 0,
  "closestPauseAt": 0,
  "closestUnpauseAt": 0,
  "pausedAt": 0,
  "inPause": true
}

schedule.Type: object · nullable

schedule.Required fields: nextPauseAt, nextUnpauseAt, closestPauseAt, closestUnpauseAt, pausedAt, inPause

schedule.Required field types: nextPauseAt (number; required), nextUnpauseAt (number; required), closestPauseAt (number; required), closestUnpauseAt (number; required), pausedAt (number; required), inPause (boolean; required)

schedule.Trading sessions of the market. Null when it trades around the clock.

- schedule.nextPauseAt (number; required)

schedule.nextPauseAt example: 0

schedule.nextPauseAt.Type: number

schedule.nextPauseAt.Start of the next scheduled break, unix timestamp in milliseconds. `0` when the market has no breaks at all, and `9007199254740991` when none is scheduled ahead of the current one.

- schedule.nextUnpauseAt (number; required)

schedule.nextUnpauseAt example: 0

schedule.nextUnpauseAt.Type: number

schedule.nextUnpauseAt.End of the break the market is in, or of the next one, unix timestamp in milliseconds. Same `0` and sentinel rules as `nextPauseAt`.

- schedule.closestPauseAt (number; required)

schedule.closestPauseAt example: 0

schedule.closestPauseAt.Type: number

schedule.closestPauseAt.Same value as `nextPauseAt`. Kept for backward compatibility.

- schedule.closestUnpauseAt (number; required)

schedule.closestUnpauseAt example: 0

schedule.closestUnpauseAt.Type: number

schedule.closestUnpauseAt.Same value as `nextUnpauseAt`. Kept for backward compatibility.

- schedule.pausedAt (number; required)

schedule.pausedAt example: 0

schedule.pausedAt.Type: number

schedule.pausedAt.Start of the break currently running, unix timestamp in milliseconds. `0` when the market is trading.

- schedule.inPause (boolean; required)

schedule.inPause example: true

schedule.inPause.Type: boolean

schedule.inPause.Whether the market is inside a scheduled break right now. Orders are refused while it is.

Example



```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "config": {
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "settlementToken": "USD",
    "type": "base",
    "name": "BTC",
    "description": "Market description",
    "ticker": "BTC/USD",
    "imageLink": "https://app.storm.tg/markets/btc.png",
    "tags": [
      "Crypto"
    ],
    "category": "crypto",
    "priority": 0
  },
  "state": {
    "indexPrice": "1000000000",
    "blockTimestamp": 0,
    "fundingRate": "1000000000",
    "nextFundingAt": 0,
    "lastFundingAt": 0,
    "vpiSpread": "1000000000",
    "vpiMarketDepthLong": "1000000000",
    "vpiMarketDepthShort": "1000000000",
    "vpiCoefficientLong": "1000000000",
    "vpiCoefficientShort": "1000000000"
  },
  "settings": {
    "fee": "1000000000",
    "minInitMarginRatio": "1000000000",
    "initMarginRatio": "1000000000",
    "maintenanceMarginRatio": "1000000000",
    "maxLeverageByAccount": {
      "key": "1000000000"
    },
    "spreadLimit": "1000000000",
    "maxPriceImpact": "1000000000",
    "maxPriceSpread": "1000000000",
    "maxOpenNotionalLong": "1000000000",
    "maxOpenNotionalShort": "1000000000",
    "minStopTriggerDistanceRatio": "1000000000",
    "isCloseOnly": true,
    "isClosed": true,
    "isPaused": true,
    "isZeroSpread": true
  },
  "change": {
    "initialPrice": 0,
    "initialPrice1h": 0,
    "initialPrice4h": 0
  },
  "schedule": {
    "nextPauseAt": 0,
    "nextUnpauseAt": 0,
    "closestPauseAt": 0,
    "closestUnpauseAt": 0,
    "pausedAt": 0,
    "inPause": true
  }
}
```