OpenAPI Specification
openapi: 3.1.0
info:
title: Forum Account Orders API
version: '1.0'
description: 'The Forum API provides programmatic access to the Forum perpetual futures exchange.
Trade attention-based perpetual futures, access real-time market data, and manage your account.
## Base URL
All endpoints are relative to `https://api.forum.market/v1`.
## Authentication
Public endpoints (market data, exchange status) require no authentication.
Private endpoints (orders, positions, account) require HMAC-SHA256 signed requests.
See the [Authentication](/api-reference/authentication) guide for details.
'
contact:
name: Forum Support
email: contact@forum.market
url: https://forum.market
termsOfService: https://forum-legal.s3.us-east-2.amazonaws.com/terms-of-service.pdf
servers:
- url: https://api.forum.market/v1
description: Production
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
tags:
- name: Orders
description: Order placement, cancellation, and queries
paths:
/orders:
post:
operationId: createOrder
summary: Place an order
description: Place a new order in a market. Requires `trade` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'201':
description: Order placed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: Order rejected (insufficient margin, reduce-only violation, etc.)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INSUFFICIENT_MARGIN
message: Insufficient margin to place order
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
get:
operationId: listOrders
summary: List open orders
description: Returns open orders with optional filtering. Requires `read` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
parameters:
- name: ticker
in: query
schema:
type: string
description: Filter by market ticker
- name: side
in: query
schema:
type: string
enum:
- buy
- sell
description: Filter by order side
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 500
default: 100
- name: cursor
in: query
schema:
type: string
description: Opaque pagination cursor from a previous response
responses:
'200':
description: Paginated list of orders
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedOrders'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: cancelAllOrders
summary: Cancel all open orders
description: Cancel all open orders, optionally filtered by market ticker. Requires `trade` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
parameters:
- name: ticker
in: query
schema:
type: string
description: Cancel only orders for this market
responses:
'200':
description: Cancellation result
content:
application/json:
schema:
$ref: '#/components/schemas/CancelAllResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
/orders/{orderId}:
get:
operationId: getOrder
summary: Get order by ID
description: Returns an order by its exchange-assigned ID. Requires `read` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
parameters:
- $ref: '#/components/parameters/OrderIdPath'
responses:
'200':
description: Order details
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: cancelOrder
summary: Cancel order by ID
description: Cancel an open order by its exchange-assigned ID. Requires `trade` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
parameters:
- $ref: '#/components/parameters/OrderIdPath'
responses:
'200':
description: Cancelled order
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/orders/client/{clientOrderId}:
get:
operationId: getOrderByClientId
summary: Get order by client order ID
description: Returns an order by its client-provided ID. Requires `read` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
parameters:
- $ref: '#/components/parameters/ClientOrderIdPath'
responses:
'200':
description: Order details
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: cancelOrderByClientId
summary: Cancel order by client order ID
description: Cancel an open order by its client-provided ID. Requires `trade` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
parameters:
- $ref: '#/components/parameters/ClientOrderIdPath'
responses:
'200':
description: Cancelled order
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/orders/batch:
post:
operationId: batchCreateOrders
summary: Place multiple orders
description: Place up to 10 orders in a single request. Each order is processed independently. Requires `trade` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateRequest'
responses:
'201':
description: Batch creation result
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: batchCancelOrders
summary: Cancel multiple orders
description: Cancel up to 20 orders in a single request. Each cancellation is processed independently. Requires `trade` permission.
tags:
- Orders
security:
- ForumAccessKey: []
ForumAccessTimestamp: []
ForumAccessSign: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCancelRequest'
responses:
'200':
description: Batch cancellation result
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCancelResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
components:
responses:
Forbidden:
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INSUFFICIENT_PERMISSIONS
message: API key lacks required permission
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: NOT_FOUND
message: Resource not found
RateLimited:
description: Rate limit exceeded
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: RATE_LIMIT_EXCEEDED
message: Rate limit exceeded. Try again in 5 seconds.
BadRequest:
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INVALID_PARAMETER
message: Request validation failed
details:
fields:
- field: ticker
message: Required
Unauthorized:
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: UNAUTHORIZED
message: Missing or invalid authentication
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INTERNAL_ERROR
message: An unexpected error occurred
schemas:
BatchCancelRequest:
type: object
required:
- orderIds
properties:
orderIds:
type: array
description: Order IDs
minItems: 1
maxItems: 20
items:
type: integer
example:
- 123
- 456
- 789
ErrorResponse:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
example: INVALID_PARAMETER
message:
type: string
description: Human-readable error message
example: Request validation failed
details:
type: object
description: Additional error details
example:
fields:
- field: ticker
message: Required
CreateOrderRequest:
type: object
required:
- ticker
- side
- qty
- orderType
properties:
ticker:
type: string
description: Market ticker symbol
example: OPENAI
side:
type: string
enum:
- buy
- sell
example: buy
qty:
type: number
description: Order quantity (positive)
example: 10
price:
type: number
description: Limit price in cents. Required for limit orders, must not be set for market orders.
example: 10050
orderType:
type: string
enum:
- market
- limit
description: '- `market`: Execute immediately at best available price
- `limit`: Place at a specific price
'
example: limit
timeInForce:
type: string
enum:
- goodTillCancel
- fillOrKill
- fillAndKill
description: 'Time-in-force policy. Required for limit orders, must not be set for market orders.
- `goodTillCancel`: Rests on the book until filled or cancelled
- `fillOrKill`: Must fill entirely immediately or be cancelled
- `fillAndKill`: Fill as much as possible immediately, cancel remainder
'
example: goodTillCancel
clientOrderId:
type: string
description: Client-generated order ID for idempotency and tracking
example: my-order-001
postOnly:
type: boolean
default: false
description: Reject if the order would match immediately (maker-only). Only valid for limit orders with goodTillCancel time-in-force.
example: false
reduceOnly:
type: boolean
default: false
description: Order can only reduce an existing position
example: false
selfTradePreventionMode:
type: string
enum:
- cr
- ci
- cb
default: cr
description: 'Self-trade prevention mode:
- `cr`: Cancel resting order
- `ci`: Cancel incoming order
- `cb`: Cancel both orders
'
example: cr
CancelAllResult:
type: object
required:
- cancelled
- orders
properties:
cancelled:
type: integer
description: Number of orders cancelled
example: 3
orders:
type: array
items:
$ref: '#/components/schemas/OrderRecord'
PaginatedOrders:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/OrderRecord'
nextCursor:
type:
- string
- 'null'
description: Cursor for the next page. Null if no more results.
example: abc123
BatchCreateRequest:
type: object
required:
- orders
properties:
orders:
type: array
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/CreateOrderRequest'
BatchCancelResult:
type: object
required:
- cancellations
properties:
cancellations:
type: array
items:
type: object
required:
- orderId
- success
properties:
orderId:
type: integer
example: 123
success:
type: boolean
example: true
error:
type: string
description: Error message if cancellation failed
BatchCreateResult:
type: object
required:
- orders
properties:
orders:
type: array
items:
type: object
properties:
clientOrderId:
type: string
example: my-order-001
order:
$ref: '#/components/schemas/OrderRecord'
error:
type: string
description: Error message if this individual order failed
example: Insufficient margin
OrderRecord:
type: object
required:
- id
- createdAt
- clientOrderId
- userId
- lockedNotional
- postOnly
- reduceOnly
- selfTradePreventionMode
properties:
id:
type: integer
description: Unique order identifier. Used in path parameters for GET/DELETE `/orders/{orderId}` and in batch cancel requests.
example: 12345
createdAt:
type: string
format: date-time
example: '2026-02-25T12:00:00.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
example: '2026-02-25T12:00:01.000Z'
clientOrderId:
type: string
description: Client-provided or server-generated order ID
example: my-order-001
userId:
type: integer
example: 42
ticker:
type:
- string
example: OPENAI
side:
type:
- string
enum:
- buy
- sell
example: buy
orderType:
type:
- string
enum:
- market
- limit
example: limit
timeInForce:
type:
- string
- 'null'
enum:
- goodTillCancel
- fillOrKill
- fillAndKill
- null
description: Time-in-force policy. Null for market orders.
example: goodTillCancel
price:
type:
- number
- 'null'
description: Limit price in cents. Null for market orders.
example: 10050
quantity:
type:
- number
description: Original order quantity
example: 10
remainingQuantity:
type:
- number
description: Unfilled quantity remaining unless status is `cancelled` or `rejected`
example: 10
status:
type:
- string
enum:
- resting
- partiallyFilled
- filled
- cancelled
- rejected
description: '- `resting`: On the order book, waiting to be filled
- `partiallyFilled`: Some quantity has been filled
- `filled`: Fully filled
- `cancelled`: Cancelled by user or system
- `rejected`: Rejected by matching engine
'
example: resting
engineOrderId:
type:
- integer
- 'null'
description: Internal matching engine order ID. Null while the order is awaiting engine acknowledgment.
example: 456
lockedNotional:
type: number
description: Cash initially held for this order in cents
example: 500
postOnly:
type: boolean
example: false
reduceOnly:
type: boolean
example: false
selfTradePreventionMode:
type: string
enum:
- cr
- ci
- cb
example: cr
parameters:
ClientOrderIdPath:
name: clientOrderId
in: path
required: true
schema:
type: string
description: Client-provided order ID
example: my-order-001
OrderIdPath:
name: orderId
in: path
required: true
schema:
type: integer
description: Order ID
example: 12345
securitySchemes:
ForumAccessKey:
type: apiKey
in: header
name: FORUM-ACCESS-KEY
description: Your API key ID (e.g. `fk_a1b2c3d4e5f6...`)
ForumAccessTimestamp:
type: apiKey
in: header
name: FORUM-ACCESS-TIMESTAMP
description: Unix epoch in seconds (UTC), as a string
ForumAccessSign:
type: apiKey
in: header
name: FORUM-ACCESS-SIGN
description: 'Base64-encoded HMAC-SHA256 signature.
**Signature generation:**
```
prehash = timestamp + method + requestPath + body
signature = Base64(HMAC-SHA256(secret, prehash))
```
'