# Common objects

## Trade

<table><thead><tr><th width="135">Property</th><th width="213">Type</th><th>Description</th></tr></thead><tbody><tr><td>tradeId</td><td>string</td><td>the unique trade identifier</td></tr><tr><td>direction</td><td>values "buy" or "sell"</td><td>identifies trade direction</td></tr><tr><td>price</td><td>string represents BigInt</td><td>price per token in the order</td></tr><tr><td>size</td><td>string represents BigInt</td><td>token quantity filled by trade</td></tr><tr><td>timestamp</td><td>number</td><td>block timestamp when the trade was concluded</td></tr><tr><td>txnHash</td><td>string</td><td>transaction in which the trade was concluded</td></tr></tbody></table>

## Order

<table><thead><tr><th width="148">Property</th><th width="213">Type</th><th>Description</th></tr></thead><tbody><tr><td>orderId</td><td>string</td><td>the order identifier</td></tr><tr><td>type</td><td>"limit" or "market"</td><td>"market" orders execute when placed</td></tr><tr><td>owner</td><td>string</td><td>a user placed the order</td></tr><tr><td>side</td><td>"bid" or "ask"</td><td>buy or sell order direction</td></tr><tr><td>price</td><td>string represents BigInt</td><td>price per token in the order </td></tr><tr><td>size</td><td>string represents BigInt</td><td>token quantity that's not filled</td></tr><tr><td>origSize</td><td>string represents BigInt</td><td>order token quantity placed by user</td></tr><tr><td>claimed</td><td>string represents BigInt</td><td>number of tokens in the order sent to the user by calling claimOrder</td></tr><tr><td>createdAt</td><td>number represents a timestamp</td><td>when the order was created</td></tr><tr><td>lastTouched</td><td>number represents a timestamp</td><td>when the order was updated</td></tr><tr><td>txnHash</td><td>string</td><td>transaction hash in which the order was created</td></tr><tr><td>status</td><td>one of "open", "filled", "claimed" or "cancel"</td><td>represents order lifecycle status</td></tr><tr><td>fee</td><td>string represents BigInt</td><td>fee for market execution</td></tr><tr><td>market</td><td>object containing a field id</td><td>a market identifier where the order was placed</td></tr></tbody></table>

## Orderbook Level

<table><thead><tr><th width="145">Property</th><th width="213">Type</th><th>Description</th></tr></thead><tbody><tr><td>price</td><td>string represents BigInt</td><td>token price, level identifier</td></tr><tr><td>size</td><td>string represents BigInt</td><td>sum of sizes in orders corresponding to the requested aggregation</td></tr><tr><td>lastTouched</td><td>number represents a timestamp</td><td>when the level was updated</td></tr></tbody></table>

## Order Fill

<table><thead><tr><th width="148">Property</th><th width="231">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>the order fill identifier</td></tr><tr><td>orderId</td><td>string</td><td>the order that was filled</td></tr><tr><td>tradeId</td><td>string</td><td>trade identifier when a part of the order is filled</td></tr><tr><td>type</td><td>"limit" or "market"</td><td>an order type</td></tr><tr><td>owner</td><td>string</td><td>a user placed the order</td></tr><tr><td>side</td><td>"bid" or "ask"</td><td>an order side</td></tr><tr><td>price</td><td>string represents BigInt</td><td>price per token in the order </td></tr><tr><td>size</td><td>string represents BigInt</td><td>token quantity that was filled in the trade</td></tr><tr><td>txnHash</td><td>string</td><td>transaction hash in which the order was filled</td></tr><tr><td>market</td><td>object containing a field id</td><td>a market identifier where the order was placed</td></tr></tbody></table>

## Candle

<table><thead><tr><th width="144">Property</th><th width="264">Type</th><th>Description</th></tr></thead><tbody><tr><td>market</td><td>object containing field id</td><td>a market identifier to which the candle is related</td></tr><tr><td>resolution</td><td>one of "15", "60", "240" or "1D"</td><td>represents a candle time interval </td></tr><tr><td>time</td><td>number represents a timestamp</td><td>with the resolution makes up a candle identifier</td></tr><tr><td>open</td><td>string</td><td>an open price</td></tr><tr><td>high</td><td>string</td><td>a high price</td></tr><tr><td>low</td><td>string</td><td>a low price</td></tr><tr><td>close</td><td>string</td><td>a close price</td></tr><tr><td>volume</td><td>string</td><td>a sum of trade sizes</td></tr><tr><td>lastTouched</td><td>number represents timestamp</td><td>when the candle was updated</td></tr></tbody></table>

## Market

<table><thead><tr><th width="206">Property</th><th width="213">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>the market identifier</td></tr><tr><td>name</td><td>string</td><td>the name of a market</td></tr><tr><td>symbol</td><td>string</td><td>the market short name</td></tr><tr><td>baseToken</td><td><a href="#token">token</a> object</td><td>the. X token of the market pair</td></tr><tr><td>quoteToken</td><td><a href="#token">token</a> object</td><td>the. Y token of the market pair</td></tr><tr><td>orderbookAddress</td><td>string</td><td>a market contract address</td></tr><tr><td>aggregations</td><td>array of numbers</td><td>market aggregation types</td></tr><tr><td>coinMarketCapId</td><td>string</td><td>a pair identifier at <a href="https://coinmarketcap.com/">https://coinmarketcap.com/</a></td></tr><tr><td>lowPrice24h</td><td>string</td><td>a lowest day price</td></tr><tr><td>highPrice24h</td><td>string</td><td>a highest day price</td></tr><tr><td>lastPrice</td><td>string</td><td>a last trade price</td></tr><tr><td>price24h</td><td>string</td><td>the price one day ago</td></tr><tr><td>bestAsk</td><td>string</td><td>the lowest ask price in an order book</td></tr><tr><td>bestBid</td><td>string</td><td>the highest bid price in an order book</td></tr><tr><td>tradingVolume24h</td><td>string</td><td>the sum of trade sizes from the last day</td></tr><tr><td>supportsNativeToken</td><td>boolean</td><td>indicates if one of the tokens is native</td></tr><tr><td>isNativeTokenX</td><td>boolean</td><td>indicates which token is native</td></tr><tr><td>tokenXScalingFactor</td><td>number</td><td>scaling applied to the base token in contract API</td></tr><tr><td>tokenYScalingFactor</td><td>number</td><td>scaling applied to the quote token in contract API</td></tr><tr><td>priceScalingFactor</td><td>number</td><td>scaling applied to the price in contract API</td></tr><tr><td>totalSupply</td><td>string</td><td>total supply data from CoinMarketCap</td></tr><tr><td>lastTouched</td><td>timestamp</td><td>when the market object was updated</td></tr><tr><td>aggressiveFee</td><td>string</td><td>the fee rate for market orders</td></tr><tr><td>passiveFee</td><td>string</td><td>the fee rate for limit orders</td></tr><tr><td>passiveOrderPayout</td><td>string</td><td>the payout rate for limit orders</td></tr></tbody></table>

## Token

<table><thead><tr><th width="187">Property</th><th width="231">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>the token identifier</td></tr><tr><td>name</td><td>string</td><td>the name of a token</td></tr><tr><td>symbol</td><td>string</td><td>the token short name</td></tr><tr><td>contractAddress</td><td>string</td><td>a token ledger address</td></tr><tr><td>decimals</td><td>number</td><td>a decimals parameter in token contract</td></tr><tr><td>roundingDecimals</td><td>number</td><td>the precision of the displayed token amount</td></tr><tr><td>supportsPermit</td><td>boolean</td><td>indicates whether the token supports permit approval</td></tr></tbody></table>

## Contract-to-human scaling transformation

As mentioned in Contract API section all token amounts and prices are scaled by corresponding scaling factors  It performs in this manner. The market API object has fields `tokenXScalingFactor. tokenYScalingFactor, priceScalingFactor`. If we want to calculate the human-readable value of the price, we should divide it by 10 raised to the power of the negative price scaling factor.&#x20;

E.g., the price value 6780 for the SUSDC market with a `priceScalingFactor` of 4 is the 0.678 human-readable price.

The same transformation says that a size of 1,234,567 for the SUSDC market with a `priceScalingFactor` of 3 is actually 1,234.567 S.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xpressprotocol.com/for-developers/api/common-objects.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.