Skip to main content
POST
Create a trading account

Authorizations

X-API-Key
string
header
required

Organization API key (hp_live_...), sent in the X-API-Key header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A full-access key can call every endpoint in this reference. A read-only key can call GET endpoints (and create a trading stream token); any other request returns 403 READ_ONLY_KEY. A key with an IP allowlist returns 403 IP_NOT_ALLOWED from any other address. Each endpoint lists which keys can call it under Access.

Headers

Idempotency-Key
string

Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with Idempotency-Replayed: true) instead of repeating the change. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. A response that contains a credential (such as a new API key or signing secret) is not saved: the change is still not repeated, and a retry returns 409 IDEMPOTENCY_KEY_COMPLETED with the original status in originalStatus. Server errors (5xx) are not saved, so a retry runs again. If the key cannot be recorded, the request is not run and returns 503 IDEMPOTENCY_UNAVAILABLE; retry with the same key.

Maximum string length: 255

Body

application/json
type
enum<string>
required

Account type

Available options:
evaluation,
sim_funded,
competition
Example:

"evaluation"

tradingPlanId
string
required

ID of the trading plan (get from /trading-plans)

Example:

"550e8400-e29b-41d4-a716-446655440000"

tradingRuleId
string

Override default rules (optional)

Example:

"660e8400-e29b-41d4-a716-446655440000"

traderId
string

Hyperprop user ID of a trader who already has an account with your firm (or is bound to one of your customers). Provide EITHER traderId OR email (exactly one). Any other ID gets 404 TRADER_NOT_FOUND; for a new customer use unassigned: true with claimEmail. Email and name are auto-resolved from the user profile.

Example:

"11111111-1111-4111-8111-111111111111"

email
string

Email of a trader who already has an account with your firm. Resolved to their user ID server-side. Provide EITHER traderId OR email (exactly one). For a new customer use unassigned: true with claimEmail.

Example:

"john@example.com"

unassigned
enum<boolean>

Create the account with NO trader attached. The response (and the account.created webhook) contains a one-time importKey — hand it to your customer, and they redeem it inside the Hyperprop app under Trading Accounts → Import. Billing and market-data entitlement start at redemption, not at creation. Mutually exclusive with traderId/email.

Available options:
true
Example:

true

claimEmail
string

Optional, only together with unassigned: true. Your customer's email address. When a Hyperprop user with this exact email (case-insensitive) has VERIFIED that address, the account links to them automatically the next time the signed-in user is loaded (the Hyperprop app does this whenever it opens; the sign-in call alone does not) — no import key needed. Matching is exact; unverified addresses never claim. A customer whose Hyperprop login existed before you set the claim email confirms the link in the app first (claimStatus stays waiting until then). The importKey stays valid as a fallback.

Maximum string length: 320
Example:

"jane@example.com"

traderProfile
object

Optional, only together with claimEmail. Identity and address you already hold for this customer. When the account is linked to the customer through claimEmail, these values fill their Hyperprop profile, but only the first time and only if the profile is completely empty: if the customer (or any firm) has already set any identity or address field, nothing is applied. If every required field is sent, the customer does not need to complete the identity form; they still accept the CME market data agreement themselves. Never returned in responses or webhooks, and discarded once the account is linked. Not used when the account is linked by import key.

markets
enum<string>[]

Markets this account may trade. Omit to use the plan's markets (the full CME Group bundle when the plan sets none). CME Group data is one inseparable licence, so naming any of CME/CBOT/NYMEX/COMEX grants all four and is billed once at the bundle rate. BINANCE (crypto perpetuals), HYPERLIQUID (index and commodity perpetuals) and HDL (Hyperprop Deep Liquidity crypto perpetuals) are licensed separately, are free public data, and are selected on their own — send ["BINANCE"] for a crypto-only account or include them alongside a CME market. An account trading only perpetuals is not billed for CME market data. Every organization is enabled for the CME Group bundle. Perpetuals (BINANCE, HYPERLIQUID, HDL) must each be enabled for your organization by Hyperprop; until then, a request that includes one is refused with 403 MARKET_NOT_ALLOWED.

Minimum array length: 1
Available options:
CME,
CBOT,
NYMEX,
COMEX,
BINANCE,
HYPERLIQUID,
HDL
Example:
accountNumber
string

Custom account number (auto-generated if omitted). Up to 64 letters, digits, ".", "_" and "-", starting with a letter or digit. Numbers starting with SIM-BOT, PRACTICE- or DEMO- (any case) are reserved and refused with 400 VALIDATION_ERROR. Unique within your organization: a number one of your accounts already has is refused with 409 DUPLICATE_VALUE; another organization may use the same number.

Maximum string length: 64
Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
Example:

"ACME-100K-7845"

initialBalance
number

Starting balance (defaults to plan's account size). 0 is kept: send 0 for an account that starts at 0.

Required range: 0 <= x <= 100000000
Example:

100000

customerId
string

REQUIRED. Your customer's ID in YOUR system. Queryable via GET /trading-accounts?customerId=..., included in every account payload and webhook (data.customerId), and the soulbound-identity key: all accounts you create for the same customerId must end up on the same Hyperprop login (see notes). Use a stable per-customer ID, not a per-order ID.

Maximum string length: 255
Example:

"acme-cust-4471"

externalRef
string

DEPRECATED alias for customerId — accepted for backward compatibility only. Send customerId instead.

Maximum string length: 255
Example:

"acme-cust-4471"

traderExternalId
string

Your own reference for this trader. Stored on the trader record, queryable via GET /traders?externalUserId=..., and returned as trader.externalUserId in account payloads and webhooks.

Maximum string length: 255
Example:

"acme-user-4471"

metadata
object

Custom metadata - store any data you need (JSON). At most 16 KB as JSON, 50 top-level keys and 5 levels of nesting; larger metadata returns 400 METADATA_TOO_LARGE.

Example:
purchase
object

Purchase/payment details

Response

Success - Trading account created

success
boolean
Example:

true

message
string
Example:

"Trading account created successfully"

data
object
Example: