REST

Authentication

All order-related endpoints require a valid signature. The signature is created by signing the order/cancel hash with the user's private key or an authorized delegate wallet.

---

Orders

Get Open Orders

Retrieves all open orders for a user.

Endpoint: GET /api/orders

Query Parameters:

Parameter	Type	Required	Description
user	string	Yes	User's Ethereum address

Example Request:

GET /api/orders?user=0x1234567890abcdef1234567890abcdef12345678

Success Response (200):

{
  "success": true,
  "data": [
    {
      "hash": "0x...",
      "user_address": "0x...",
      "base_token": "0x...",
      "asset": "btcusd",
      "amount": "1000000000",
      "price": "10000000000000",
      "side": true,
      "nonce": 1234567890,
      "leverage": "1000000000",
      "closing_order": false,
      "remaining_amount": "1000000000",
      "closed": false,
      "stop": false,
      "stop_price": "0",
      "stopped": false,
      "is_market": false,
      "post_only": false,
      "decimals": 2,
      "amount_dec": 4,
      "margin_currency_symbol": "USDC",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Order

Creates a new trading order.

Endpoint: POST /api/order

Request Body:

{
  "hash": "0x...",
  "user_address": "0x...",
  "base_token": "0x...",
  "asset": "btcusd",
  "amount": "1000000000",
  "price": "10000000000000",
  "side": true,
  "nonce": 1234567890,
  "leverage": "1000000000",
  "closing_order": false,
  "v": 27,
  "r": "0x...",
  "s": "0x...",
  "remaining_amount": "1000000000",
  "closed": false,
  "stop": false,
  "stop_price": "0",
  "stopped": false,
  "is_market": false,
  "post_only": false,
  "decimals": 2,
  "amount_dec": 4,
  "margin_currency_symbol": "USDC",
  "replace_hash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}

Field Descriptions:

Field	Type	Description
hash	string	Order hash (keccak256 of order parameters)
user_address	string	User's Ethereum address
base_token	string	Margin currency token address
asset	string	Trading pair symbol (e.g., "btcusd", "ethusd")
amount	string	Order amount (as string, scaled by 1e8)
price	string	Order price (as string, scaled by 1e8)
side	boolean	true = buy/long, false = sell/short
nonce	integer	Unique nonce for the order
leverage	string	Leverage amount (scaled by 1e8), 0 for cross margin
closing_order	boolean	true if this is a reduce-only order
v, r, s	-	ECDSA signature components
remaining_amount	string	Remaining unfilled amount
stop	boolean	true if this is a stop order
stop_price	string	Trigger price for stop orders
is_market	boolean	true for market orders
post_only	boolean	true to only add liquidity (maker only)
replace_hash	string	Hash of order to replace (for order amendments)

Success Response (200):

{
  "success": true,
  "message": "Order created",
  "data": {
    "hash": "0x..."
  }
}

Error Response (400):

{
  "success": false,
  "error": "Insufficient balance"
}

Possible Errors:

• Nonce too large

• Invalid order hash - please refresh and try again

• Invalid Signature

• Delegate expired

• Order with this hash already exists

• Maximum 100 open orders allowed

• Insufficient balance

• Leverage too high

• Too much leverage

• Minimum order value is 10 USD

• Maximum order value for this asset is X USD

• Min acceptable price is X

• Max acceptable price is X

---

Cancel Order

Cancels an existing open order.

Endpoint: POST /api/cancel-order

Request Body:

{
  "order_hash": "0x...",
  "v": 27,
  "r": "0x...",
  "s": "0x..."
}

Field Descriptions:

Field	Type	Description
order_hash	string	Hash of the order to cancel
v, r, s	-	ECDSA signature of the order hash

Success Response (200):

{
  "success": true,
  "message": "Order cancelled",
  "data": {
    "hash": "0x..."
  }
}

Error Response (400):

{
  "success": false,
  "error": "Order not found"
}

Possible Errors:

• Order not found

• Liquidation order cannot be canceled

• Invalid Signature

• Delegate expired

---

Trades

Get User Trades

Retrieves trade history for a user (last 100 trades).

Endpoint: GET /api/trades

Query Parameters:

Parameter	Type	Required	Description
user	string	Yes	User's Ethereum address

Example Request:

GET /api/trades?user=0x1234567890abcdef1234567890abcdef12345678

Success Response (200):

{
  "success": true,
  "data": [
    {
      "hash": "0x...",
      "user": "0x...",
      "asset": "btcusd",
      "base_token": "0x...",
      "amount": "1000000000",
      "price": "10000000000000",
      "side": true,
      "fee": "100000",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

---

Positions

Get Open Positions

Retrieves all open positions for a user.

Endpoint: GET /api/positions/open

Query Parameters:

Parameter	Type	Required	Description
user	string	Yes	User's Ethereum address

Example Request:

GET /api/positions/open?user=0x1234567890abcdef1234567890abcdef12345678

Success Response (200):

{
  "success": true,
  "data": [
    {
      "tx_hash": "0x...",
      "hash": "0x...",
      "base_token": "0x...",
      "asset": "btcusd",
      "side": true,
      "size": "1000000000",
      "entry_block": "12345678",
      "value": "50000000000",
      "entry_price": "10000000000000",
      "last_price": "10100000000000",
      "mark_price": 0.5,
      "liquidation_price": "9000000000000",
      "margin": "5000000000",
      "unrealized_pnl": "100000000",
      "realized_pnl": "0",
      "funding_rate": "100000",
      "decimals": 2,
      "amount_dec": 4,
      "margin_dec": 6,
      "margin_symbol": "USDC",
      "profit": "0",
      "loss": "0",
      "funding_cost": "0",
      "ur_funding_cost": "0",
      "created_at": "2024-01-15T10:30:00Z",
      "liquidated": false,
      "global_mm": 0.005,
      "is_cross": false,
      "cross_margin": "0"
    }
  ]
}

---

Get Closed Positions

Retrieves closed positions for a user (last 100).

Endpoint: GET /api/positions/closed

Query Parameters:

Parameter	Type	Required	Description
user	string	Yes	User's Ethereum address

Example Request:

GET /api/positions/closed?user=0x1234567890abcdef1234567890abcdef12345678

Success Response (200):

{
  "success": true,
  "data": [
    {
      "tx_hash": "0x...",
      "hash": "0x...",
      "base_token": "0x...",
      "asset": "btcusd",
      "side": true,
      "liquidated": false,
      "profit": "500000000",
      "loss": "0",
      "funding_cost": "10000000",
      "ur_funding_cost": "0",
      "created_at": "2024-01-15T10:30:00Z",
      "global_mm": 0.005,
      "decimals": 2,
      "amount_dec": 4
    }
  ]
}

---

Binary Contracts

Get Settled Binary Contracts

Retrieves historical settled binary contracts for a given underlying asset and contract duration.

Endpoint: GET /settled-binary-contracts

Query Parameters:

Parameter	Type	Required	Description
underlying	string	Yes	Underlying asset symbol (e.g., "BTCUSDT", "ETHUSDT")
contractLife	integer	Yes	Contract duration in minutes (e.g., 15, 60)

Example Request:

GET /settled-binary-contracts?underlying=btcusd&contractLife=15

Success Response (200):

[
  {
    "symbol": "BTCUSDT-1706356800-105000-15",
    "underlying_symbol": "BTCUSDT",
    "target": 105000.00,
    "final_price": 105234.56,
    "is_above_target": true,
    "started_at": 1706356800,
    "settled_at": 1706357700
  },
  {
    "symbol": "BTCUSDT-1706355900-104500-15",
    "underlying_symbol": "BTCUSDT",
    "target": 104500.00,
    "final_price": 104123.45,
    "is_above_target": false,
    "started_at": 1706355900,
    "settled_at": 1706356800
  }
]

Response Field Descriptions:

Field	Type	Description
symbol	string	Unique binary contract identifier
underlying_symbol	string	The underlying asset (e.g., "BTCUSD")
target	float	Strike/target price for the contract
final_price	float	Settlement price at contract expiry
is_above_target	boolean	true if final price was above target
started_at	integer	Contract start time (Unix timestamp)
settled_at	integer	Contract settlement time (Unix timestamp)

Error Responses:

Status	Message
400	Missing required parameter: underlying
400	Missing required parameter: contractLife
400	Invalid contractLife parameter
500	Failed to fetch settled contracts

---

Error Handling

All endpoints return errors in a consistent format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes:

Code	Description
200	Success
400	Bad Request (validation error, business logic error)
405	Method Not Allowed

---

Notes

• All *big.Int values are represented as strings to preserve precision

• Amounts and prices are scaled by 1e8 unless otherwise specified

• Timestamps are in ISO 8601 format (UTC)

• Ethereum addresses and hashes should include the 0x prefix