Orders
Place, cancel, and query orders on the 4rho prediction market CLOB.
Place Order
POST /v1/orders
Scope: trade:orders
Placing orders requires both HMAC API key authentication (request headers) and an EIP-712 signature (request body). See the EIP-712 Signing guide for prerequisites and examples.
Request Body
{
"market_id": "550e8400-e29b-41d4-a716-446655440000",
"token_id": "12345678901234567890",
"side": "BUY",
"maker_amount": "1000000",
"taker_amount": "2000000",
"maker": "0xYourWalletAddress",
"signer": "0xYourWalletAddress",
"taker": "0x0000000000000000000000000000000000000000",
"salt": "123456789",
"nonce": 0,
"expiration": 0,
"fee_rate_bps": 200,
"signature": "0x...",
"outcome_index": 0,
"time_in_force": "GTC",
"post_only": false,
"stp_mode": ""
}
| Field | Type | Required | Description |
|---|---|---|---|
market_id | UUID | Yes | Market to trade on |
token_id | string | Yes | ERC-1155 token ID for the outcome |
side | string | Yes | BUY or SELL |
maker_amount | string | Yes | Amount the maker provides (wei) |
taker_amount | string | Yes | Amount the maker receives (wei) |
maker | string | Yes | Maker wallet address |
signer | string | Yes | Signer wallet address |
taker | string | Yes | Taker address (zero for open) |
salt | string | Yes | Random salt for order uniqueness |
nonce | int | Yes | Order nonce |
expiration | int | No | Unix timestamp (0 = no expiry) |
fee_rate_bps | int | Yes | Fee rate in basis points |
signature | string | Yes | EIP-712 signature (signing guide) |
outcome_index | int | Yes | Outcome index (0 = Yes, 1 = No) |
time_in_force | string | No | GTC, GTD, FOK, FAK (default: GTC) |
post_only | bool | No | Reject if would cross the book |
stp_mode | string | No | Self-trade prevention mode |
Response
{
"order_id": "550e8400-e29b-41d4-a716-446655440000",
"order_hash": "0xabc123...",
"status": "open",
"matches": 0
}
| Status | Description |
|---|---|
open | Resting on the book, no fills |
partially_filled | Some fills, remainder resting |
filled | Fully filled |
Cancel Order
DELETE /v1/orders/:hash
Scope: trade:orders
Cancels an open or partially filled order by its order hash.
Response
{ "message": "order cancelled" }
Get Order
GET /v1/orders/:hash
Scope: read:account
Returns the full order details including current status and fill amounts.
Response
{
"id": "550e8400-...",
"order_hash": "0xabc123...",
"market_id": "...",
"side": "BUY",
"price": "0.50000000",
"status": "open",
"remaining": "1000000",
"filled_amount": "0",
"time_in_force": "GTC",
"post_only": false,
"created_at": "2024-03-01T00:00:00Z"
}
Get Open Orders
GET /v1/orders/open/:market_id
Scope: read:account
Returns all open and partially filled orders for the authenticated user in a specific market.
Get Order Book
GET /v1/orders/book/:market_id?outcome=0&levels=20
Public — No authentication required.
| Parameter | Type | Default | Description |
|---|---|---|---|
outcome | int | 0 | Outcome index |
levels | int | 20 | Max price levels per side |
Response
{
"market_id": "...",
"outcome_index": 0,
"bids": [
{ "price": "0.50", "quantity": "5000000" },
{ "price": "0.49", "quantity": "3000000" }
],
"asks": [
{ "price": "0.52", "quantity": "2000000" },
{ "price": "0.55", "quantity": "4000000" }
]
}
Cancel-Replace
POST /v1/orders/cancel-replace
Scope: trade:orders
Atomically cancels an existing order and places a new one. If the cancellation fails, the new order is not placed.
Request Body
{
"cancel_hash": "0xoriginal_order_hash...",
"new_order": {
"market_id": "...",
"side": "BUY",
"maker_amount": "1500000",
"taker_amount": "3000000",
...
}
}
Amend Order
PUT /v1/orders/:hash/amend
Scope: trade:orders
Modify the price or quantity of a resting order. If the price changes or quantity increases, the order loses time priority (moved to back of queue).
Request Body
{
"maker_amount": "2000000",
"taker_amount": "4000000"
}
Response
{
"order_hash": "0xabc123...",
"status": "open",
"price": "0.50000000",
"remaining": "2000000",
"time_priority": false,
"price_changed": true
}