> For the complete documentation index, see [llms.txt](https://docs.xpressprotocol.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xpressprotocol.com/for-developers/api/contract-api.md).

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