[!TIP]
Deposit Method Selection:
This page explains Standard Vault Deposit, where the user connects their wallet and invokes the smart contract deposit function.
If your users are depositing from a Centralized Exchange (CEX) or using a custodial wallet that does not support DApps, refer to the Deposit by Transfer guide.
Deposit
Token deposits can be made on supported chains (list here). Check Get supported collateral info for the token/chain combination. The steps and USDC examples below describe an ERC20 deposit. For native OKB on X Layer, skip approval and follow Native OKB deposits on X Layer. To create a deposit request:1
For ERC20 tokens, approve spending by the Vault smart contract
Native tokens do not use ERC20 approval.Get Vault & USDC contract addresses from the Smart Contract Addresses page.
All our smart contracts are verified, meaning you can retrieve the Vault & Token ABIs from the block explorers of any supported mainnets or testnets.
[!IMPORTANT] The addresses and RPC nodes used in the following examples are for Arbitrum Sepolia testnet. Since Orderly is an omnichain protocol, when deploying to production, replace these with the correct contract addresses and RPC endpoints for your target chain.
Example code
Example code
2
Determine necessary deposit fee in WEI
Example code
Example code
3
Call the deposit function of the smart contract
Contains the following structured data:where:
Example code
Example code
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.
Full example
Code generation via ABI file
Code generation via ABI file
- Java
- TypeScript
- install Web3j CLI
web3j generate solidity -a <./path/to/Vault.json> -o <./out-path/to/Vault.java> -p <package-name>
USDG deposits on Arbitrum
USDG on Arbitrum One (chain ID42161) is an ERC20 token. Use its token and Vault addresses with the standard ERC20 deposit flow above: approve the Vault to spend USDG, set tokenHash to keccak256(utf8("USDG")), and call deposit. USDG uses 6 decimals both on Arbitrum and in the Orderly ledger; for example, 100 USDG is 100000000 token units.
The USDG principal is transferred via the ERC20 allowance. Transaction value covers only the quoted Vault deposit fee when enabled; the fee and transaction gas are paid in ETH on Arbitrum. Deposit by Transfer is not supported for USDG on Arbitrum; use the standard Vault deposit flow.
Native OKB deposits on X Layer
For X Layer mainnet (chain_id=196), OKB is the native token. Use the Vault at 0x816f722424B49Cf1275cc86DA9840Fbd5a6167e9, also listed on the Smart Contract Addresses page.
- Do not call
approveor send OKB directly to the Vault address. Call the payable Vaultdepositfunction so the deposit is associated with the correct Orderly account and broker. - Set
tokenHashtokeccak256(utf8("OKB")):0x4526a805bc924644101a6ea6f6a02af9e68a2bd1b0f3c8b3f38c9cf5e19a5a50. - Set
tokenAmountto the deposit principal in 18-decimal on-chain units. For example,0.1 OKBis100000000000000000. - When
depositFeeEnabled()is true, quotegetDepositFee(receiver, depositInput)immediately before submission. Set transactionvalueto principal + quoted fee, both in the native token’s smallest unit. Only the principal is credited as collateral. Transaction gas is paid separately in OKB. - After the cross-chain deposit completes, verify the credited amount in Orderly. Ledger precision is 8 decimals, so use amounts representable at that precision;
0.1 OKBcorresponds to10000000ledger units. Do not send the 8-decimal ledger integer as the on-chain deposit amount.
TypeScript
chain_details[].contract_address="". An empty address is not an ERC20 address; do not substitute a wrapped-token contract. exclusive_deposit_supported=false means the Deposit by Transfer flow is not available for this token/chain pair.
Withdrawal
For USDG withdrawals to Arbitrum One, settoken="USDG" and chainId=42161 in the withdrawal message, and encode amount with 6 decimals. For example, a gross withdrawal of 100 USDG is 100000000 in the signed message and "100000000" in the REST payload. With the current 1 USDG withdrawal fee and zero cross-chain withdrawal fee, the receiver gets 99 USDG. Check Get supported collateral info for current fees.
For OKB withdrawals to X Layer, use token="OKB" and chainId=196 in the withdrawal message. Encode amount using the token-level 8 decimals returned by Get supported collateral info, not the chain’s 18 decimals. For example, a gross withdrawal of 0.1 OKB is 10000000 in the signed message and "10000000" in the REST payload. With the current 0.01 OKB withdrawal fee and zero cross-chain withdrawal fee, the receiver gets 0.09 OKB as native OKB.
Read the current fees and minimum amount from the API before withdrawing. The requested amount must exceed the applicable fees and minimum amount. OKB supports withdrawals only to its configured X Layer chain; its rebalance path is disabled.
[!WARNING]
PnL Settlement Requirement: Any realized profit from open or recently closed positions must be settled via the Settle PnL flow before it can be added to your withdrawable_balance. If you attempt to withdraw without settling your PnL, the withdrawal amount may exceed your available balance and fail. See Settle PnL for details.
To withdraw tokens from Orderly:
1
Choose a valid chain to withdraw your funds to
A list of supported chains can be found on our Smart Contract Addresses page.
2
Check if the chain has sufficient liquidity
Since Orderly is an omnichain trading infrastructure, the liquidity of withdrawn assets might need to move across chains. If there is not enough liquidity of the withdrawn asset on the target chain, then an
additional cross-chain transaction fee will be deducted from the user’s account.
3
Obtain a withdrawal nonce
Get a nonce from Get Withdrawal Nonce API.
4
Obtain a signature from EIP-712
5
Make a withdraw request
Call the Create withdraw request API.
Full Example
Unlike key registration which uses the off-chain domain, a withdrawal signature requires the on-chain domain targeting the Orderly Ledger contract. Furthermore, note the type formatting difference:- In the EIP-712 cryptography signature message,
amountmust be represented as a numeric value (uint256/BigInt). - In the final REST API JSON payload, the
amountfield must be serialized as a String.