Request to Settle PnL

Orderly

Home

Introduction

Build on Omnichain

NEAR

SDKs

Troubleshooting

Changelog

Get a Grant

Socials

Get in Touch

pre-release

Perpetual Futures

Orderly Home Page

A Unified Trading Infrastructure for Decentralized Exchanges

What is Orderly?

Key Advantages

Connecting traders across chains: The omnichain approach

Our Mission

Roadmap

Overview of $ORDER

Distribution and Emission Schedule

Retroactive Airdrop

Trading Rewards

Trading Rewards Mechanism

Market Making Rewards

Market Making Rewards Mechanism

Staking

Staking Information

esORDER

$ORDER Related Smart Contract Addresses

Getting Started

Orderly Orderbook Design

Glossary

Perpetual Futures Trading

Accounts

Order Types

Trading Fees

Formulas and Definitions

Margin, Leverage & PnL

Mark Price, Index Price, and Last Price

Order Price Limit

Funding Rate

Liquidations

The Orderly Insurance Fund functions as a safeguard to protect bankrupt traders from being insolvent.

Insurance Fund & ADL

Supported Markets

Supported Chains

There are several front ends built on top of the Orderly mainnet with many more in development.

Builders

Security

Terms of Service

Privacy Policy

Smart Contract Addresses

Authentication/Key Management

Withdrawal

General Data Access

User Data

Storage Staking

System Overview

Smart Contract Overview

Partner Support

Structured approach to integrating with Orderly

Integration Checklist

Integration FAQs

Overview of wallet authentication & Orderly keys

Wallet Authentication

Deposit/Withdrawal

Settle PnL

Overview of order management related actions

Order Management

Custom Fee Structure

Delegate Signer

Referral System

All requests need to be signed using `orderly-key` and `orderly-secret`.

API Authentication

Errors consist of three parts: an error code and a message. Codes are universal, but messages can vary. Here is the error JSON payload:

Error Codes


**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/volume/stats`

Get the latest volume statistics of Orderly and its associated builders. Note that for builder volume, the volume is counted as the sum of the maker and taker volume, while for the full Orderly platform, the volume is the total amount matched on the platform (ie taker and maker are not double-counted.)


Get Builder Volume


**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/broker/name?broker_id={broker_id}`

Get the list of builders currently onboarded on Orderly.


Get Builder List

**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/chain_info`

Get chains specified builder is available on.


Get Supported Chains per Builder


**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/futures_market`

Get market volume filtered by broker.


Get Market Volume by Broker


**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/balance/stats`

Get TVL(Total Balance + Unsettled PnL) by broker


Get TVL by Broker

**Limit: 1 requests per 1 second per IP address**

`GET /v1/public/system_info`

Retrieve the current system maintenance status of Orderly. A return value of status = 0 means the system is functioning properly and a return value of status = 2 means the system is under maintenance.

Get System Maintenance Status

Get Vault Balance


**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/insurancefund`


Get Insurance Fund Info

**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/announcement`

Get Announcements


**Limit: 10 requests per 1 second per IP address**

`GET /v1/ip_info`


Get IP Info

For `EVM`:

`GET https://testnet-operator-evm.orderly.org/v1/faucet/usdc`

For `Solana`:

`GET https://testnet-operator-sol.orderly.org/v1/faucet/usdc`

Receive 1,000 USDC in the EVM Testnet environment or 100 USDC in the Solana Testnet environment. Each account may only use the faucet a maximum of 5 times.

This API is only available on Testnet so make sure to use Testnet domain as above instead of Mainnet domain.

Get Faucet USDC(Testnet Only)

**Limit: 10 requests per 1 second per IP address**

`GET /v1/public/account`

Check if provided account account is registered with Orderly and it's respective builder.

Check if Account Exists

**Limit: 10 requests per 1 second per IP address**

`GET /v1/get_account`

Check whether a wallet has a registered account with provided broker_id.


Check if Wallet is Registered

**Limit: 10 requests per 1 second per IP address**

`GET /v1/get_broker`

Check whether an address is registered already.


Check if Address is Registered

**Limit: 10 requests per 1 second per IP address**

`GET /v1/registration_nonce`

Retrieve a nonce used for registering an account on Orderly. The validity of the nonce value is `2` minutes. Each nonce can only be used once (ie for one account).

Get Registration Nonce

**Limit: 10 requests per 1 second per IP address**

`POST /v1/register_account`

Registers a new account to Orderly. Note an account is unique for each wallet address + builder id (ie the same wallet address can have multiple accounts with Orderly, 1 with each builder)


Register Account

**Limit: 10 requests per 1 second per IP address**

`GET /v1/get_orderly_key`

Check the validity of an Orderly access key attached to the account.


Get Orderly Key

**Limit: 10 requests per 1 second per IP address**

`POST /v1/orderly_key`

Adds an Orderly access key to an account.


Add Orderly Key

**Limit: 10 requests per 1 second per IP address**

`POST /v1/client/remove_orderly_key`

Remove an Orderly key from an account, deactivating it from all usage


Remove Orderly Key

**Limit 10 requests per 60 seconds**

`GET /v1/client/key_info`

Retrieve all the registered Orderly key pairs under the account.


Get Current Orderly Key Info

**Limit 10 requests per 60 seconds**

`GET /v1/client/orderly_key_ip_restriction`

Retrieves the current IP restriction of a particular Orderly key.


Get Orderly Key IP Restriction

**Limit: 10 requests per 60 seconds**

`POST /v1/client/set_orderly_key_ip_restriction`

Set the IP restrictions of a particular Orderly key under the account.


Set Orderly Key IP Restriction

**Limit: 10 requests per 60 seconds**

`POST /v1/client/reset_orderly_key_ip_restriction`

Reset the IP restriction of a particular Orderly key under the account.


Reset Orderly Key IP Restriction

**Limit 10 requests per 60 seconds**

`GET /v1/volume/user/daily`


Get User Daily Volume

**Limit 10 requests per 60 seconds**

`GET /v1/volume/user/stats`

Get User Volume Statistics

**Limit: 10 requests per 60 seconds**

`GET /v1/client/statistics`

Get statistics of the user account


Get User Statistics

**Limit: 10 requests per 60 seconds**

`GET /v1/client/info`

Get basic account information including current user fee rates.


Get Account Information

**Limit 10 requests per 60 seconds**

`GET /v1/client/statistics/daily`

Get user daily statistics of assets/pnl/volume.


Get User Daily Statistics

**Limit: 10 requests per 60 seconds**

`GET /v1/notification/inbox/notifications`

Get all notifications for the user.

Currently the only supported message type is the order filled message.


Get All Notifications

**Limit: 10 requests per 60 seconds**

`GET /v1/notification/inbox/unread`

Get the information on unread messages for the user.


Get Unread Notifications

**Limit: 10 requests per 60 seconds**

`POST /v1/notification/inbox/mark_read`

Set the read status on a list of notifications for a user.


Set Read Status of Notifications

**Limit: 10 requests per 60 seconds**

`POST /v1/notification/inbox/mark_read_all`

Set the read status on all notifications for a user.


Set Read Status of All Notifications

**Limit: 5 requests per 60 second per user**

`POST /v1/client/leverage`

Choose maximum leverage for futures mode


Update Leverage Setting

**Limit: 10 requests per 1 second per IP address**

`POST /v1/public/leverage`

Get max leverage setting


Get Max Leverage Setting


**Limit: 10 requests per 1 second per IP address**

`GET v1/public/config`


Get Leverage Configuration

**Limit: 10 requests per 60 seconds**

`POST /v1/client/maintenance_config`

Set the user config for whether the system should automatically cancel the user's pending orders during maintenance.


Set Maintenance Config

**Limit: 1 requests per second**

`POST /v1/delegate_signer`


**Limit: 1 requests per second**

`POST /v1/delegate_orderly_key`


Add Delegate Signer Orderly Key

**Limit: 1 requests per second**

`POST /v1/delegate_settle_pnl`


Delegate Signer Settle PnL

**Limit: 1 requests per second**

`POST /v1/delegate_withdraw_request`


Delegate Signer Withdraw Request

**Limit: 10 requests per 1 second**

`POST /v1/order`

Place order maker/taker, the order executed information will be update from websocket stream.
will response immediately with an order created message.

`MARKET` type order behavior: it matches until the full size is executed. If the size is too large (larger than whole book) or the matching price exceeds the price limit (refer to `price_range`), then the remaining quantity will be cancelled.

`IOC` type order behavior: it matches as much as possible at the order_price. If not fully executed, then remaining quantity will be cancelled.

`FOK` type order behavior: if the order can be fully executed at the order_price then the order gets fully executed otherwise would be cancelled without any execution.

`POST_ONLY` type order behavior: if the order will be executed with any maker trades at the time of placement, then it will be cancelled without any execution.

`ASK` type order behavior: the order price is guranteed to be the best ask price of the orderbook at the time it gets accepted.

`BID` type order behavior: the order price is guranteed to be the best bid price of the orderbook at the time it gets accepted.

`visible_quantity` behavior: it sets the maximum quantity to be shown on orderbook. By default, it is equal to order_quantity, negative number and number larger than `order_quantity` is not allowed. If it sets to 0, the order would be hidden from the orderbook. It doesn't work for `MARKET`/`IOC`/`FOK` orders since orders with these types would be executed and cancelled immediately and not be shown on orderbook. For `LIMIT`/`POST_ONLY` order, as long as it's not complete, `visible_quantity` is the maximum quantity that shown on orderbook.

`order_amount` behavior: for `MARKET`/`BID`/`ASK` order, order can be placed by `order_amount` instead of `order_quantity`. It's the size of the order in terms of the quote currency instead of the base currency. The order would be rejected if  both `order_amount` and `order_quantity` are provided. The precision of the number should be within 8 digits.

`client_order_id` behavior: customized order_id, a unique id among open orders. Orders with the same `client_order_id` can be accepted only when the previous one if completed, otherwise the order will be rejected.

For `MARKET`/`BID`/`ASK` order, `order_amount` is not supported when placing SELL order while `order_quantity` is not supported when placing BUY order.

Note: This endpoint requires `trading` scope in Orderly Key.

Create Order

**Limit: 1 request per 1 second**

`POST /v1/batch-order`

Creates a batch of orders as a list according to the same rules as a single Create Order.

Parameters for each order within the batch will be the same as the create single order. The batch of orders should be sent as a JSON array containing all the orders. The maximum number of orders that can be sent in 1 batch order request is 10. Each order within the batch order request is counted as 1 order towards the overall create order rate limit.



Note: This endpoint requires `trading` scope in Orderly Key.

Batch Create Order

**Limit: 10 requests per 1 second**

`POST /v1/algo/order`

Place maker/taker order that requires an additional trigger for order execution such as stop orders.

`STOP` type order bahavior: an order to buy or sell at the market/limit price once the asset has traded at or through a specified price (the "stop price"). If the asset reaches the stop price, the order becomes a market order and is filled at the next available market price.

To place `Positional TP/SL` order, the input fields is 2 layer and includes an array of the objects named childOrder. The take-profit or stop-loss order should be the objects in the array. For the sub-order in childOrder, please input `CLOSE_POSITION` as type, and `TAKE_PROFIT` or `STOP_LOSS` in algoType field.

Sample request can be found [here](/docs/build-on-evm/algo-order-samples)

Note: This endpoint requires trading scope in Orderly Key.

Create Algo Order

**Limit: 10 request per 1 second**

`PUT /v1/order`

Edit a pending order by `order_id`. Only the `order_price` or `order_quantity` can be amended.

Note: This endpoint requires `trading` scope in Orderly Key.

Edit Order

**Limit: 10 requests per 1 second**

`PUT /v1/algo/order`

Edit a pending algo order by `order_id`. Only the price or quantity can be amended.

Note: This endpoint requires trading scope in Orderly Key.

Edit Algo Order

**Limit: 10 requests per 1 second**

`DELETE /v1/order?order_id={order_id}&symbol={symbol}`

Cancels a single order by `order_id`.

Note: This endpoint requires `trading` scope in Orderly Key.


Cancel Order

**Limit: 10 requests per 1 second**

`DELETE /v1/algo/order?order_id={order_id}&symbol={symbol}`

Cancels a single algo order by `order_id`.


Cancel Algo Order

**Limit: 10 requests per 1 second**

`DELETE /v1/client/order?client_order_id={client_order_id}&symbol={symbol}`

Cancel an order by `client_order_id`.

Note: This endpoint requires `trading` scope in Orderly Key.


Cancel Order By client_order_id

**Limit: 10 requests per 1 second**

`DELETE /v1/algo/client/order?client_order_id={client_order_id}&symbol={symbol}`

Cancel an algo order by `client_order_id`.

Cancel Algo Order By client_order_id

**Limit: 10 requests per 1 second**

`DELETE /v1/algo/orders?symbol={symbol}`

Cancel all pending algo orders.

Cancel All Pending Algo Orders

**Limit: 10 requests per 1 second**

`DELETE /v1/orders?symbol={symbol}`

Cancel a list of orders, filtered by `symbol` optionally. This request will cancel all open orders within the filter criteria, and will cancel all open orders if no filter is provided.

Note: This endpoint requires `trading` scope in Orderly Key.


Cancel All Pending Orders

**Limit: 1 request per 1 second**

`POST /v1/order/cancel_all_after`

Cancels all of the user's ordinary and algo orders after being called (dead man switch).

Note: Users must apply for access before using this endpoint.

Cancel All After

**Limit: 10 requests per 1 second**

`DELETE /v1/batch-order?order_ids={order_id1},{order_id2}`

Cancel a list of orders by `order_ids`. The maximum orders that can be cancelled within 1 batch cancel request is 10. 

This endpoint will return invalid order_id error if 0 order_ids are given or all of the given order_ids are invalid. 

Note: This endpoint requires `trading` scope in Orderly Key.


Batch Cancel Orders

**Limit: 10 requests per 1 second**

`DELETE /v1/client/batch-order?client_order_ids={client_order_id1},{client_order_id2}`

Cancel a list of orders by `client_order_ids`. The maximum orders that can be cancelled within 1 batch cancel request is 10.

This endpoint will return invalid client_order_id error if 0 client_order_ids are given or all of the given client_order_ids are invalid. 

Note: This endpoint requires `trading` scope in Orderly Key.


Batch Cancel Orders By client_order_id

**Limit: 10 requests per 1 second**

`GET /v1/order/{order_id}`

Get details of a single order by `order_id`.


Get Order by order_id

**Limit: 10 requests per 1 second**

`GET /v1/client/order/{client_order_id}`

Get details of a single order by `client_order_id`.


Get Order by client_order_id

**Limit: 10 requests per 1 second**

`GET /v1/algo/order/{order_id}`

Get details of a single algo order by order_id.

Get Algo Order by order_id

**Limit: 10 requests per 1 second**

`GET /v1/algo/client/order/{client_order_id}`

Get details of a single algo order by `client_order_id`.


Get Algo Order by client_order_id

**Limit: 10 requests per 1 second**

`GET /v1/orders`

Get orders by customized filters.

For filter by status, one can reference special bundled statuses below for ease of access of Open (ie `INCOMPLETE`) orders or `COMPLETED` orders.

- `INCOMPLETE` = `NEW` + `PARTIAL_FILLED`
- `COMPLETED` = `CANCELLED` + `FILLED`


Get Orders

**Limit: 10 requests per 1 second**

`GET /v1/algo/orders`

Get algo order details by customized filters.

For filter by status, one can reference special bundled statuses below for ease of access of Open (i.e `INCOMPLETE`) orders or `COMPLETED` orders.

`INCOMPLETE` = `NEW` + `PARTIAL_FILLED`


`COMPLETED` = `CANCELLED` + `FILLED`

Get Algo Orders

**Limit: 10 requests per 1 second**

`GET /v1/trades`

Return client’s trades history within a time range.


Get Trades

**Limit: 10 requests per 1 second**

`GET /v1/trade/{trade_id}`

Get specific transaction details by `trade_id`.


Smart Contract API

​Request to Settle PnL

Request to Settle PnL