Page 1
Private API
Introduction
The Outpoll Private API provides full access to trading, balances, positions, history, and real-time data. All endpoints require HMAC-SHA256 authentication.
Base URL
https://api.outpoll.comAll requests must be made over HTTPS.
Authentication
Every request must include three headers:
OUTPOLL-API-KEY
Your API key (starts with op_k_)
OUTPOLL-API-SIGNATURE
Base64URL-encoded HMAC-SHA256 signature
OUTPOLL-API-TIMESTAMP
Current Unix timestamp in seconds
Creating a Signature
The signature is computed over a message that concatenates the timestamp, HTTP method, request path (without query string), and request body:
message = timestamp + method + path + bodyUse only the path portion (e.g.
/orders/limit), not the full URL or query string.
Sign with your API secret:
Example (Python)
Example (JavaScript)
Timestamps must be within 30 seconds of the server time. Requests outside this window are rejected.
Do not include an
Authorization: Bearerheader alongside API key headers. Requests with both are rejected with400 Bad Request.
API Key Access Scope
API keys grant access to the following endpoints:
/orders/limit
POST
API key
/orders/market
POST
API key
/api/user-balances
GET
API key
/api/user-balances/full
GET
API key
/api/history/orders
GET
API key
/api/history/trades
GET
API key
/api/history/deals/open-positions
GET
API key
/api/history/deals/active-orders
GET
API key
/api/history/activity
GET
API key
/api/history/stats/profile/{userId}
GET
API key
/api/history/stats/profile/{userId}/positions
GET
API key
/orders/tpsl
GET/POST
API key
/orders/tpsl/{tpslId}
DELETE
API key
/orders/limit/{orderId}
DELETE
API key
/api/deposit/usdc-address
GET
JWT only
/api/transactions
GET
JWT only
Endpoints marked JWT only require a
Bearertoken obtained viaPOST /auth/login. API key authentication returns403 Forbiddenfor these endpoints.
Reusable Client (Python)
The examples below use this helper class:
API Key Management
API keys are managed via JWT-authenticated endpoints. Log in first via POST /auth/login to obtain a Bearer token.
Send Verification Code
Sends an email confirmation code required for API key creation.
Headers
Authorization
Bearer <token>
Response 200 OK
Create API Key
Headers
Authorization
Bearer <token>
Request Body
code
string
Yes
Email confirmation code
otp
string
No
2FA OTP code (if 2FA is enabled)
expiresAt
string
No
Expiration time (ISO 8601). Null = no expiry
Response 200 OK
id
string
API key record ID
key
string
Public API key
secret
string
Secret for HMAC signing
createdAt
string
Creation timestamp (ISO 8601)
expiresAt
string
Expiration timestamp or null
The
secretis shown only once upon creation. Store it securely.
Creating a new key automatically deactivates any previous key.
Get Active API Key
Headers
Authorization
Bearer <token>
Returns the active API key metadata. The secret is not returned.
Revoke API Key
Headers
Authorization
Bearer <token>
Revokes the active API key. A new key must be created to continue API access.
Orders
Place Limit Order
Place a limit order at a specific price. The order remains in the order book until filled or cancelled.
Request Body
e
string
Yes
Event ID
o
string
Yes
Outcome ID (market)
ba
string
Yes
Betting asset ID (the runner/outcome token to trade)
qa
string
Yes
Quote asset ID (USDC: 078dcd98-928d-479f-8110-ff6d27e44de2)
s
string
Yes
Side — BUY or SELL
p
number
Yes
Price (0.01–0.99)
q
number
Yes
Quantity (number of shares)
Example Request
Response 200 OK / 202 Accepted
i
string
Order ID
Python
Place Market Order
Execute an order immediately at the best available price.
Request Body
e
string
Yes
Event ID
o
string
Yes
Outcome ID (market)
ba
string
Yes
Betting asset ID
qa
string
Yes
Quote asset ID
s
string
Yes
Side — BUY or SELL
am
number
Conditional
Amount in USDC to spend (required for BUY)
q
number
Conditional
Quantity of shares to sell (required for SELL)
Example — BUY
Example — SELL
Response 200 OK / 202 Accepted
Python — BUY
Python — SELL
Cancel Order
Cancel an active limit order.
Path Parameters
orderId
string
ID of the order to cancel
Response 200 OK / 204 No Content
Python
Set Take Profit / Stop Loss
Attach TP/SL conditions to an open position. When the price hits your target, the position is automatically closed.
Request Body
e
string
Yes
Event ID
o
string
Yes
Outcome ID (market)
ba
string
Yes
Betting asset ID
qa
string
Yes
Quote asset ID
i
string
Yes
Intent — YES or NO
s
string
Yes
Side — SELL
q
number
Yes
Quantity of shares to close
t
number
No
Take-profit price (0.01–0.99)
l
number
No
Stop-loss price (0.01–0.99)
At least one of
t(take profit) orl(stop loss) must be provided.
Example Request
Response 200 OK / 202 Accepted
Python
Get TP/SL Orders
Retrieve active take-profit / stop-loss orders for a given asset.
Query Parameters
assetId
string
Yes
Asset / runner ID
primary
boolean
Yes
Filter by primary (true) or non-primary (false)
status
string
No
Filter by status (e.g. ACTIVE)
Response 200 OK
i
string
Order ID
q
number
Quantity
tpp
number
Take-profit price
slp
number
Stop-loss price
Python
Cancel TP/SL Order
Cancel an active take-profit / stop-loss order.
Path Parameters
tpslId
string
ID of the TP/SL order
Response 200 OK / 204 No Content
Python
Positions
Get Open Positions
Retrieve all open positions for the authenticated user.
Query Parameters
page
integer
No
0
Page number
size
integer
No
100
Items per page
Response 200 OK
oi
string
Order ID
ei
string
Event ID
eoi
string
Event outcome ID
ai
string
Asset ID
et
string
Event title
eic
string
Event icon URL
es
string
Event slug
eim
string
Event image URL
on
string
Outcome name
tn
string
Token name
ip
boolean
Is primary outcome
tsc
number
Total shares count
asc
number
Available shares count
sp
number
Share price (entry)
c
number
Cost
cp
number
Current price
v
number
Current value
tpsl
array
Attached TP/SL orders
pv
number
PnL value
pp
number
PnL percent
od
string
Open date (ISO 8601)
Python
Get Active Orders
Retrieve all active (unfilled) orders.
Query Parameters
page
integer
No
0
Page number
size
integer
No
100
Items per page
Response 200 OK
oi
string
Order ID
ei
string
Event ID
eoi
string
Event outcome ID
ai
string
Asset ID
et
string
Event title
eic
string
Event icon URL
es
string
Event slug
on
string
Outcome name
tn
string
Token name
ip
boolean
Is primary outcome
sc
number
Shares count
sp
number
Share price
si
string
Side — BUY or SELL
fq
number
Filled quantity
oq
number
Original order quantity
cp
number
Current price
od
string
Open date (ISO 8601)
st
string
Status
Python
Balances
Get User Balances
Retrieve balances for all coins/tokens held by the authenticated user.
Query Parameters
eventTokenIds
string
No
—
Comma-separated token IDs to filter
page
integer
No
0
Page number
size
integer
No
100
Items per page
Response 200 OK
i
string
Balance ID
u
string
User ID
et
string
Event token ID
aop
number
Average open price
c
number
Cost
v
number
Value
tv
number
Total value
Python
Get Full Balances
Retrieve balances with event/outcome metadata.
Response 200 OK
Same paginated wrapper as /api/user-balances. Each item includes the base fields plus:
eq
string
Event question
ei
string
Event icon URL
es
string
Event slug
on
string
Outcome name
tn
string
Token name
ip
boolean
Is primary outcome
Python
Deposit
Get Deposit Address
Retrieve the USDC deposit address for the authenticated user.
Response 200 OK
i
string
Asset ID
a
string
Blockchain address for deposits
Response 404 Not Found — Address not yet generated.
Python
History
Order History
Retrieve historical orders for the authenticated user.
Query Parameters
page
integer
No
0
Page number
size
integer
No
20
Items per page
eventOutcomeId
string
No
—
Filter by outcome/market ID
sort
string
No
desc
Sort direction (asc / desc)
Response 200 OK
i
string
Order ID
u
string
User ID
e
string
Event ID
o
string
Event outcome ID
a
string
Asset ID
oq
number
Original quantity
si
string
Side — BUY or SELL
t
string
Type — LIMIT or MARKET
p
number
Price
m
number
Placement time (Unix ms)
ex
string
Expire at (ISO 8601) or null
st
string
Status — ACTIVE, FILLED, CANCELLED
q
number
Quantity (filled)
Python
Trade History
Retrieve executed trades (filled orders).
Query Parameters
page
integer
No
0
Page number
size
integer
No
20
Items per page
eventOutcomeId
string
No
—
Filter by outcome/market ID
Response 200 OK
i
string
Trade record ID
t
string
Trade ID
u
string
User ID
or
string
Order ID
s
string
Side — BUY or SELL
e
string
Event ID
o
string
Event outcome ID
a
string
Asset ID
q
number
Quantity
p
number
Price
f
number
Fee
m
string
Execution time (ISO 8601)
Python
Transaction History
Retrieve a paginated list of all transactions (deposits, trades, etc.).
Query Parameters
page
integer
No
0
Page number
size
integer
No
20
Items per page
Response 200 OK
i
string
Transaction ID
u
string
User ID
a
string
Asset ID
eq
string
Event question
ei
string
Event icon URL
es
string
Event slug
on
string
Outcome name
tn
string
Token name
ip
boolean
Is primary outcome
t
string
Transaction type
am
number
Amount
s
string
Status
cat
string
Created at (ISO 8601)
e
string
External transaction ID
f
number
Fees
ta
string
Withdrawal wallet address
bu
string
Blockchain transaction URL
bn
string
Blockchain name
Python
Activity Feed
Retrieve the user's recent activity (trades, position changes).
Query Parameters
page
integer
No
0
Page number
size
integer
No
20
Items per page
Response 200 OK
u
string
User ID
tra
string
Trade record ID
n
string
Username
oi
string
Outcome ID
on
string
Outcome name
p
string
Position direction (Yes / No)
si
string
Side — BUY or SELL
q
number
Quantity
x
string
Execution time (ISO 8601)
eq
string
Event question
ei
string
Event icon URL
es
string
Event slug
tn
string
Token name
ip
boolean
Is primary outcome
pr
number
Price
ev
number
Event volume
uv
number
User volume (nullable)
This endpoint uses
t(total items) in its pagination wrapper instead of the standardtp(total pages).
Python
Profile Stats
Retrieve trading statistics for a user profile.
Path Parameters
userId
string
User ID
Response 200 OK
profile.userId
string
User ID
profile.username
string
Username
profile.joinedAt
string
Join date (ISO 8601)
profile.me
boolean
Whether this is the authenticated user
cards.positionValue
number
Total position value
cards.volumeTraded
number
Total volume traded
cards.marketsTraded
number
Number of markets traded
Python
Position Stats
Retrieve position-level statistics for a user profile, including open positions and position history.
Path Parameters
userId
string
User ID
Response 200 OK
tab
string
Active tab (nullable)
Open positions / Position history fields
ei
string
Event ID
eoi
string
Event outcome ID
ai
string
Asset ID
et
string
Event title
eic
string
Event icon URL
es
string
Event slug
on
string
Outcome name
tn
string
Token name
sc
number
Shares count
sp
number
Share price (entry)
si
string
Side — BUY or SELL
c
number
Cost
v
number
Current value
pv
number
PnL value
pp
number
PnL percent
od
string
Open date (ISO 8601) — position history only
cd
string
Close date (ISO 8601) — position history only
Both
openPositionsandpositionHistoryuse the standard paginated wrapper withti(total items).
Python
Real-time Data (WebSocket)
For detailed WebSocket documentation including all message types, authentication flows, and Python examples, see the WebSocket API document.
Errors
200
OK — Request succeeded
201
Created — Resource created successfully
202
Accepted — Request accepted for async processing
204
No Content — Success with no response body
400
Bad Request — Invalid parameters
401
Unauthorized — Missing or invalid API key / signature
403
Forbidden — Insufficient API key permissions
404
Not Found — Resource does not exist
422
Unprocessable Entity — Business logic validation error
429
Too Many Requests — Rate limit exceeded
500
Internal Server Error
Error Response (General)
s
integer
HTTP status code
e
string
Error name
m
string
Error message
p
string
Request path
t
string
Timestamp
Error Response (Order Service)
Order endpoints return a different error format with an error code:
e
string
Error code (e.g. ORD-1401)
m
string
Error message
s
integer
HTTP status code
t
string
Timestamp
d
string
Error details (optional)
Rate Limit Error
Rate Limits
API requests are rate-limited per API key using a 3-tier sliding window.
Minute
20 requests
Hour
600 requests
Day
10,000 requests
Violation escalation:
1st rate limit exceeded
Temporary block (5 minutes)
2nd violation within 2 hours
Permanent API key block
When rate-limited, the response includes a Retry-After header with the number of seconds to wait.
Pagination
Paginated endpoints accept page (0-indexed) and size query parameters.
Standard format
i
array
Items
p
integer
Current page
s
integer
Page size
tp
integer
Total pages
ti
integer
Total items (some endpoints)
Last updated
Was this helpful?

