# Contract API

You can trade tokens from deposits in the market contract or from token ledgers. 

Market contracts represent a pair of tokens, named X and Y, or base and quote. All token amounts and prices are scaled by corresponding scaling factors unless otherwise stated. Also see [Contract-to-human scaling transformation](/for-developers/api/common-objects.md#contract-to-human-scaling-transformation).

## depositTokens

Move funds to the market contract to trade them.

### Parameters

<table><thead><tr><th width="190">Parameter</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td>token_x_amount</td><td>uint128</td><td>the amount of token X to deposit</td></tr><tr><td>token_y_amount</td><td>uint128</td><td>the amount of token Y to deposit</td></tr></tbody></table>

## withdrawTokens

Move funds from market contracts to token ledgers.

### Parameters

<table><thead><tr><th width="190">Parameter</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td>withdraw_all</td><td>bool</td><td>if set to True, withdraws all the trader's tokens; otherwise, uses the specified amounts.</td></tr><tr><td>token_x_amount</td><td>uint128</td><td>the amount of token X to withdraw (ignored if withdraw_all is true)</td></tr><tr><td>token_y_amount</td><td>uint128</td><td>the amount of token Y to withdraw (ignored if withdraw_all is true)</td></tr></tbody></table>

## placeOrder

Create an order in the market contract. The function supports receiving the native token instead of the corresponding wrapped token.

### Parameters

<table><thead><tr><th width="244">Parameter</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>isAsk</td><td>bool</td><td>true if the order is a sell order, false if it is a buy order</td></tr><tr><td>quantity</td><td>uint128</td><td>the amount of the base token in the order</td></tr><tr><td>price</td><td>uint56</td><td>the price per token in the order, no more than 6 significant digits</td></tr><tr><td>max_commission</td><td>uint128</td><td>the maximum commission, which may include passive and/or aggressive fees</td></tr><tr><td>market_only</td><td>bool</td><td>indicates if the order should be executed only against existing orders in the market</td></tr><tr><td>post_only</td><td>bool</td><td>indicates if the order should be posted only and not executed immediately</td></tr><tr><td>transfer_executed_tokens</td><td>bool</td><td>flag for transferring executed tokens (true) or crediting them to the balance (false)</td></tr><tr><td>expires</td><td>uint256</td><td>the time at which the order will expire</td></tr></tbody></table>

## placeOrder

Overloaded version. Create an order in the market contract with the permitted approval.

### Parameters

<table><thead><tr><th width="244">Parameter</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>isAsk</td><td>bool</td><td>true if the order is a sell order, false if it is a buy order</td></tr><tr><td>quantity</td><td>uint128</td><td>the amount of the base token in the order</td></tr><tr><td>price</td><td>uint56</td><td>the price per token in the order, no more than 6 significant digits</td></tr><tr><td>max_commission</td><td>uint128</td><td>the maximum commission, which may include passive and/or aggressive fees</td></tr><tr><td>amount_to_approve</td><td>uint128</td><td>the amount of  the token permitted by the signature</td></tr><tr><td>market_only</td><td>bool</td><td>indicates if the order should be executed only against existing orders in the market</td></tr><tr><td>post_only</td><td>bool</td><td>indicates if the order should be posted only and not executed immediately</td></tr><tr><td>transfer_executed_tokens</td><td>bool</td><td>flag for transferring executed tokens (true) or crediting them to the balance (false)</td></tr><tr><td>expires</td><td>uint256</td><td>the time at which the order will expire</td></tr><tr><td>v</td><td>uint8</td><td>the component V of the signature</td></tr><tr><td>r</td><td>bytes32</td><td>the component R of the signature</td></tr><tr><td>s</td><td>bytes32</td><td>the component S of the signature</td></tr></tbody></table>

## placeMarketOrderWithTargetValue

Create a market order by specifying the exact value of token Y. The function supports receiving the native token instead of the corresponding wrapped token.

### Parameters

<table><thead><tr><th width="244">Parameter</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>isAsk</td><td>bool</td><td>true if the order is a sell order, false if it is a buy order</td></tr><tr><td>target_token_y_value</td><td>uint128</td><td>the amount of the quote token to be spent by the order</td></tr><tr><td>price</td><td>uint56</td><td>the price per token in the order, no more than 6 significant digits</td></tr><tr><td>max_commission</td><td>uint128</td><td>the maximum commission</td></tr><tr><td>transfer_executed_tokens</td><td>bool</td><td>flag for transferring executed tokens (true) or crediting them to the balance (false)</td></tr><tr><td>expires</td><td>uint256</td><td>the time at which the order will expire</td></tr></tbody></table>

## placeMarketOrderWithTargetValue

Overloaded version. Create a market order by specifying the exact value of token Y with the permitted approval.

### Parameters

<table><thead><tr><th width="244">Parameter</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>isAsk</td><td>bool</td><td>true if the order is a sell order, false if it is a buy order</td></tr><tr><td>target_token_y_value</td><td>uint128</td><td>the amount of the quote token to be spent by the order</td></tr><tr><td>price</td><td>uint56</td><td>the price per token in the order, no more than 6 significant digits</td></tr><tr><td>max_commission</td><td>uint128</td><td>the maximum commission</td></tr><tr><td>amount_to_approve</td><td>uint128</td><td>the amount of  the token permitted by the signature</td></tr><tr><td>transfer_executed_tokens</td><td>bool</td><td>flag for transferring executed tokens (true) or crediting them to the balance (false)</td></tr><tr><td>expires</td><td>uint256</td><td>the time at which the order will expire</td></tr><tr><td>v</td><td>uint8</td><td>the component V of the signature</td></tr><tr><td>r</td><td>bytes32</td><td>the component R of the signature</td></tr><tr><td>s</td><td>bytes32</td><td>the component S of the signature</td></tr></tbody></table>

## changeOrder

Claiming/canceling an existing order and creating a new one in the same (bid/ask) direction.

### Parameters

<table><thead><tr><th width="190">Parameter</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td>old_order_id</td><td>uint64</td><td>the identifier of the order to modify, a new order id will be assigned to the order</td></tr><tr><td>new_quantity</td><td>uint128</td><td>the amount of tokens for the new order</td></tr><tr><td>new_price</td><td>uint56</td><td>the price per token in the order, no more than 6 significant digits</td></tr><tr><td>max_commission</td><td>uint128</td><td>the maximum commission, which may include passive and/or aggressive fees</td></tr><tr><td>post_only</td><td>bool</td><td>indicates if the order should be posted only and not executed immediately</td></tr><tr><td>transfer_tokens</td><td>bool</td><td>if true, tokens will be transferred to the order owner</td></tr><tr><td>expires</td><td>uint256</td><td>the time at which the order will expire</td></tr></tbody></table>

## claimOrder

Allows a trader to claim or cancel the order.

### Parameters

<table><thead><tr><th width="190">Parameter</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td>order_id</td><td>uint64</td><td>the identifier of the order to claim</td></tr><tr><td>transfer_tokens</td><td>bool</td><td>if true, transfers the tokens to the trader's address</td></tr><tr><td>expires</td><td>uint256</td><td>the time at which the order will expire</td></tr></tbody></table>


---

# 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/contract-api.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.