Skip to main content
PATCH
Update 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

Path Parameters

accountId
string
required

The trading account ID

Body

application/json
metadata
object

Custom metadata. Replaces existing metadata wholesale unless mergeMetadata is true. At most 16 KB as JSON, 50 top-level keys and 5 levels of nesting; larger metadata returns 400 METADATA_TOO_LARGE.

Example:
mergeMetadata
boolean

When true, the provided metadata keys are merged into the existing metadata instead of replacing it entirely

Example:

true

status
enum<string>

Account status

Available options:
not_started,
in_progress,
passed,
failed,
expired
Example:

"passed"

initialBalance
number

Initial account balance

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

100000

currentBalance
number

Current account balance

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

105000

highWaterMark
number

Highest balance achieved

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

107500

customerId
string

Reassign the account to a different customer of yours (resale, correction). Cannot be cleared — every account always has a customerId. On linked accounts the new customerId must not be bound to a different Hyperprop login (409 CUSTOMER_ALREADY_BOUND).

Maximum string length: 255
Example:

"acme-cust-4471"

externalRef
string

DEPRECATED alias for customerId — use customerId instead. Null is ignored (customerId cannot be cleared).

Maximum string length: 255
Example:

"acme-cust-4471"

reason
string

Reason for the change (logged in audit trail)

Maximum string length: 1000
Example:

"Balance adjustment for data feed error"

Response

Account updated successfully

success
boolean
Example:

true

message
string
Example:

"Trading account updated successfully"

data
object