Order signing

The TypeScript and Python SDKs build and sign orders for you. This page describes what they do, so you can sign orders from a language without an SDK, such as Rust or Go. If an SDK fits your stack, use it instead.

An order is EIP-712 typed data. You fill in the order's fields, hash them with the domain of the market's exchange, sign the hash, and send the signed order to POST /v1/orders as shown in Place orders.

The domainCopy Anchor Link

The market's isNegRisk and isYieldBearing fields decide the exchange. An order signed for the wrong exchange is rejected with create_order_contract_invalid_signature.

These are the CTFExchange and NegRiskCtfExchange contracts on Deployed contracts.

The orderCopy Anchor Link

The order type is:

Order(uint256 salt,address maker,address signer,address taker,uint256 tokenId,uint256 makerAmount,uint256 takerAmount,uint256 expiration,uint256 nonce,uint256 feeRateBps,uint8 side,uint8 signatureType)

In the request body, send the uint256 fields as decimal strings and side and signatureType as numbers, as in the request example. The hash you send is the order's EIP-712 hash, the one you sign.

AmountsCopy Anchor Link

A limit order's amounts must match its price exactly, or the order is rejected with create_order_limit_amounts_mismatch. Compute them like this, in integers:

1. Pick pricePerShare in wei. It's above 0 and below 10^18, with at most the market's decimalPrecision decimals: a multiple of 10^16 when decimalPrecision is 2, and of 10^15 when it's 3.
2. For a buy, takerAmount is the number of shares in wei, and makerAmount is pricePerShare × takerAmount / 10^18, rounded down.
3. For a sell, makerAmount is the number of shares in wei, and takerAmount is pricePerShare × makerAmount / 10^18, rounded down.

The amount that sets the price, makerAmount for a buy and takerAmount for a sell, must also be a multiple of 10^10, or the order is rejected with create_order_price_field_precision_invalid. The SDKs keep the number of shares to 5 significant digits, which makes it one for any order of at least 1 share.

For example, buying 10 shares at 0.40 gives a takerAmount of 10000000000000000000 and a makerAmount of 4000000000000000000.

A market order's amounts come from walking the order book, with your slippage. The API rejects one whose signed average price is more than 1% better for you than its pricePerShare, with create_order_market_amounts_mismatch. The SDKs' getMarketOrderAmounts is the reference for that calculation.

Sign with a regular walletCopy Anchor Link

Sign the typed data with any EIP-712 implementation, the same way eth_signTypedData_v4 does. The signature is the usual 65 bytes, r, s and v.

To check your encoding, hash this order. The domain is BNB Mainnet's exchange for markets that are neither negative-risk nor yield-bearing.

{
  "salt": "123456789",
  "maker": "0x1111111111111111111111111111111111111111",
  "signer": "0x1111111111111111111111111111111111111111",
  "taker": "0x0000000000000000000000000000000000000000",
  "tokenId": "1000000000000000000",
  "makerAmount": "4000000000000000000",
  "takerAmount": "10000000000000000000",
  "expiration": "4102444800",
  "nonce": "0",
  "feeRateBps": "200",
  "side": 0,
  "signatureType": 0
}

Sign with a Predict accountCopy Anchor Link

A Predict account is a Kernel smart account (version 0.3.1). The exchange checks its signatures through the account, with ERC-1271. Your Privy wallet signs, and maker and signer are the account's address.

To sign a hash H for the account:

1. Wrap it for Kernel: wrapped = keccak256(abi.encode(keccak256("Kernel(bytes32 hash)"), H)).
2. Hash it with the account's EIP-712 domain: digest = keccak256(0x1901 ‖ domainSeparator ‖ wrapped). The domain is name Kernel, version 0.3.1, the chainId, and the account's address as verifyingContract.
3. Sign digest with the Privy wallet as a personal message (EIP-191), over its 32 bytes.
4. Prefix the 65-byte signature with the byte 0x01 and the address of the ECDSA validator, 0x845ADb2C711129d4f3966735eD98a9F09fC4cE57. The result is 86 bytes.

For an order, H is the order's EIP-712 hash. To log in, H is the EIP-191 hash of the message from GET /v1/auth/message, and the signer you send is the account's address.

The ECDSA validator has the same address on BNB Mainnet and BNB Testnet.