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": 50,
  "signature": "0x...",
  "outcome_index": 0,
  "time_in_force": "GTC",
  "post_only": false
}

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	Must be the zero address — directed orders are not supported
`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

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_index=0&levels=20

Public — No authentication required.

Parameter	Type	Default	Description
`outcome_index`	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
}