Skip to main content

​
Accounts / Access keys

​
Account Structure

A wallet owner can register an account on Orderly for each builder that is supported. Each wallet owner could thus have multiple accounts (that are not interlinked with each other) registered with Orderly.

​
Account ID

Each account is identified by an account id, which can be calculated by
  1. Converting the wallet address to bytes
  2. Converting the keccak256 hash of the brokerId string to bytes
  3. Concatenating (1) and (2)
  4. Convert back to Hex String, the keccak256 hash of the result of (3)

​
Authorization

Orderly relies on the EIP-712 standard to authenticate wallets and accounts for critical actions, such as:
  • Account creation
  • Access key (Orderly key) addition
  • Withdrawal requests
For these actions, wallet owners will need to sign specific messages from their wallet and pass the signature through the REST APIs to complete the action. The following sections describe the steps needed to complete these actions. In addition, depositing into Orderly is a direct on-chain transaction that requires signing from the wallet owner. For other actions, such as calling trading-related RESTful APIs, only the Orderly Key is required.

​
Access key (Orderly key)

Orderly uses the ed25519 elliptic curve standard for access keys. Users can generate access keys using any public ed25519 libraries (such as this one) and then be added to any account through a REST API. Access keys can have different scopes. A read scope API can access all private read-only APIs, and a trading scope can, in addition, access all order APIs (create order, batch create order, edit order, cancel order, cancel order by client_order-Id, cancel orders in bulk, batch cancel orders, batch cancel orders by client_order_id). Access keys also have expirations for security reasons. The maximum allowed expiration of an access key is 365 days.

​
Account Registration

Follow the following steps to register an account on Orderly:
  1. Choose a valid chain/builder to register the account on
  2. Check if the wallet is already registered via this API or if account already exists via this API.
  3. Get a nonce from Get registration nonce API
  4. Sign a message from the wallet in the following format using the EIP-712 standard and obtain the signature
{
  "brokerId": "woofi_dex",
  "chainId": 80001,
  "timestamp": 1685973017064,
  "registrationNonce": "194528949540"
}
where:
NameTypeRequiredDescription
brokerIdstringYBuilder ID
chainIdintYChain ID of registering chain (within those that are supported by the Network)
timestamptimestampYtimestamp in UNIX milliseconds
registrationNoncestringYValid nonce from Get registration nonce

​
Add Access Key

Follow the following steps to add a new access key on Orderly:
  1. Generate an ed25519 key-pair
  2. Sign a message from the wallet in the following format using the EIP-712 standard and obtain the signature
{
  "brokerId": "woofi_dex",
  "orderlyKey": "ed25519:HqN9uKJioHjAJZbadgQRGzq2e7huKg6foCyNY43hWbCk",
  "scope": "trading",
  "timestamp": 1685973094398,
  "expiration": 1686081094398
}
where:
NameTypeRequiredDescription
brokerIdstringYBuilder ID
chainIdintYChain ID of registering chain (within those that are supported by the Network)
orderlyKeystringYed25519 public key
scopestringYvalid scopes are read, trading; multiple scopes can be sent, comma separated
timestamptimestampYtimestamp in UNIX milliseconds
expirationtimestampYExpiration time of the key in UNIX milliseconds. Maximum allowed expiration is 365 days from add
  1. Send all the necessary information via Add Orderly key API Users can also check the validity of a particularly Orderly access key via the Get Orderly key API.

​
Deposits / Withdrawals

​
Deposit

Token deposits can be made on any supported chains To create a deposit request, users can follow the following steps:
  1. Approve spending of the token by the smart contract
  2. Call the deposit function of the smart contract, containing the following structured data
NameTypeRequiredDescription
accountIdbytesYThe account id of the user in bytes.
brokerHashbytesYThe keccak256 hash of the builder id (eg “woofi_dex”)
tokenHashbytesYThe keccak256 hash of the token string (eg “USDC”)
tokenAmountintYAmount of tokens to be deposited
Note that deposits will take some time to reflect depending on the origin chain, to allow for finalizing of the cross-chain transaction involved in the deposit. Once the deposit is credited, the balance will update and the transaction can be seen on the Get asset history API.

​
Withdrawal

Follow the following steps to withdraw your tokens from Orderly:
  1. Choose a valid chain to withdraw your funds to
  2. Check if the chain has sufficient liquidity
  3. Get a withdrawal nonce
  4. Sign an EIP-712 message in the following format
{
  "brokerId": "woofi_dex",
  "chainId": 80001,
  "receiver": "0x036Cb579025d3535a0ADcD929D05481a3189714b",
  "token": "USDC",
  "amount": "1000000",
  "withdrawNonce": 1,
  "timestamp": 1685973017064
}
where
NameTypeRequiredDescription
brokerIdstringYBuilder ID
chainIdintYChain ID of withdrawing chain (within those that are supported by the Network)
receiverstringYAddress of the receiver, which should be equal to the address of the account.
tokenstringYThe string representation of the token that is being withdrawn (eg “USDC”)
amountstringYAmount of tokens to be withdrawn
withdrawNonceintYValid withdrawal nonce from Get withdrawal nonce
timestamptimestampYcurrent timestamp in UNIX milliseconds
  1. Call the request to withdraw API to complete the withdrawal request

​
Settle PnL

Any realized and unrealized PnL accrued from open or closed positions needs to be “Settled” into the USDC balance of the account. PnL settlement can happen anytime for any account if other users trigger a settlement. Any user can also trigger PnL settlement of their own account by following these steps:
  1. Get a Settle PnL nonce
  2. Sign an EIP-712 message in the following format
{
  "brokerId": "woofi_dex",
  "chainId": 80001,
  "settleNonce": 1,
  "timestamp": 1685973017064
}
where: Name Type Required Description brokerId string Y Builder ID chainId int Y Chain ID of registering chain (within those that are supported by the Network) settleNonce int Y Valid settlement nonce from Get Settle PnL nonce timestamp timestamp Y current timestamp in UNIX milliseconds
  1. Call the Settle PnL API to complete the request
NameTypeRequiredDescription
brokerIdstringYBuilder ID
chainIdintYChain ID of registering chain (within those that are supported by the Network)
settleNonceintYValid settlement nonce from Get Settle PnL nonce
timestamptimestampYcurrent timestamp in UNIX milliseconds