Update a trading account
Update an existing trading account. This is the endpoint for reflecting anything that happens on your side — payouts, manual passes, balance corrections, risk decisions — onto the account. Only organization admins (or API keys with write/admin permission) can update accounts.
Allowed fields:
| Field | Description |
|---|---|
status | Account status: not_started, in_progress, passed, failed, expired. Reopening an account (or setting the balance of an open one) at or below a loss floor a payout locked is refused with 409 BALANCE_AT_OR_BELOW_LOCKED_FLOOR: it would fail at the trader’s first trade. Use POST /trading-accounts/bulk-update with resetToInitial to start it over |
initialBalance | Starting balance |
currentBalance | Set the current balance. On an active account the change is applied as the difference to the live balance at that moment, so trades booked meanwhile are kept; it does not count toward the day’s P&L and is also listed under GET /trading-accounts/{accountId}/balance-adjustments. On a passed, failed or expired account the balance is set as sent. For deposits and withdrawals prefer POST /trading-accounts/{accountId}/balance-adjustments with your own reference |
highWaterMark | Highest balance achieved |
customerId | Reassign the account to a different customer of yours (resale, correction). Look accounts up later with GET /trading-accounts?customerId=.... Cannot be cleared, and on linked accounts the new customer must not be soulbound to a different Hyperprop login (409 CUSTOMER_ALREADY_BOUND) |
metadata | Custom JSON — notes, tags, payout records, anything you need (see merge semantics below) |
mergeMetadata | true = merge the provided keys into existing metadata. Omitted/false = replace metadata wholesale |
reason | Why you made the change — stored in the audit trail and included in webhook events |
Metadata: replace vs merge
By default, metadata replaces the stored object entirely. Send "mergeMetadata": true to update only the keys you pass and preserve the rest:
// Stored: { "tier": "gold", "notes": "VIP" }
// Request: { "metadata": { "notes": "VIP - churned" }, "mergeMetadata": true }
// Result: { "tier": "gold", "notes": "VIP - churned" }
The merge is shallow (top-level keys only). Nested objects and arrays are replaced as a whole — so to append to an array (e.g. a payouts list), first read the current metadata via GET /trading-accounts/{accountId}, append your entry, and send the full array back with mergeMetadata: true. Metadata is opaque to Hyperprop: we store and return it verbatim, but never compute on it.
Recipe — record a payout / balance withdrawal:
Hyperprop has no built-in payout ledger — payouts stay in your system. The pattern below reflects the withdrawal on the balance and keeps an auditable record on the account:
curl -X PATCH "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}" \
-H "X-API-Key: hp_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"currentBalance": 48000,
"reason": "Payout PO-1042 - 2000 USD withdrawal",
"mergeMetadata": true,
"metadata": {
"payouts": [
{ "id": "PO-1042", "type": "balance_withdrawal", "amount": 2000, "currency": "USD", "date": "2026-07-08", "status": "paid" }
],
"totalPaidOut": 2000
}
}'
The same pattern works for any custom workflow (e.g. recording a drawdown-lock decision under a metadata.mll key): make the risk decision in your system, then persist the resulting balance/status here plus a metadata record of why.
Example — manually pass an account:
curl -X PATCH "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}" \
-H "X-API-Key: hp_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"status": "passed", "reason": "Trader hit target during feed outage", "mergeMetadata": true, "metadata": {"manualPass": true}}'
Example — balance correction:
curl -X PATCH "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}" \
-H "X-API-Key: hp_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"currentBalance": 52500, "highWaterMark": 52500, "reason": "Balance adjustment for data feed error"}'
Status change side effects:
passed,failed, orexpiredautomatically setscompletedAt. Live market data is not switched off at once: the trader keeps it until the end of the billed month, and it ends at 23:50 US Central on the month’s last day only if they then have no active account at any firmnot_startedclearsstartedAt,completedAt, andviolationReason(full reset)- Before the status moves to
passed,failed,expiredornot_started, the account’s open positions are closed at market and its working orders cancelled (the orders carry the reasonAdmin flatten: <who> — Account set to <status>). If trading does not confirm that, the status is not changed and the request answers502 CLOSE_NOT_CONFIRMED. Once the account haspassed,failedorexpired, anything opened in the meantime is closed as well
Audit trail & webhooks:
Every change is logged with before/after values and who made it — inspect via GET /trading-accounts/{accountId}/changes or the org-wide GET /audit-log. Changes made with an API key are attributed to that key (adminEmail: "api-key", with the key’s ID recorded); session changes are attributed to the admin’s email. Changes also emit webhook events to your configured endpoints: account.status_changed (plus account.passed/account.failed convenience events) for status changes, and account.updated for balance/metadata changes — each carrying your reason and the previous values.
Error responses:
Every error returns { statusCode, error, message, code } — switch on code:
| Status | code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | Payload failed validation (empty payload, invalid status value, wrong types) |
| 400 | NO_FIELDS_TO_UPDATE | No updatable field was provided |
| 401 | UNAUTHORIZED | Missing/invalid API key or session |
| 403 | INSUFFICIENT_PERMISSIONS / NOT_ADMIN | Key or user lacks admin/write permission |
| 404 | ACCOUNT_NOT_FOUND | No account with this ID exists in your organization |
| 422 | INSUFFICIENT_BALANCE | A lower currentBalance would take the live balance below zero on an account that starts above 0 (accounts that start at 0 may go below zero); the balance was not changed |
| 500 | UPDATE_ACCOUNT_ERROR | Unexpected server error |
| 502 | CLOSE_NOT_CONFIRMED | Trading did not confirm that the open positions and orders were closed before a status change; nothing was changed — check the positions and send the request again |
| 503 | ENGINE_NOT_CONFIRMED | The change was saved but trading did not confirm it yet — send the same request again |
| 503 | OUTCOME_UNKNOWN / ADJUSTMENT_NOT_APPLIED | The balance change could not be confirmed, or was not applied — check the balance before sending it again |
Other fields in the same request are saved even when the balance change is refused; the message says so.
Access: full-access API keys only (a read-only key gets 403 READ_ONLY_KEY). Dashboard members need manage access to Traders & accounts.
curl --request PATCH \
--url https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"metadata": {
"notes": "VIP customer",
"supportTicket": "TKT-123"
},
"mergeMetadata": true,
"status": "passed",
"initialBalance": 100000,
"currentBalance": 105000,
"highWaterMark": 107500,
"customerId": "acme-cust-4471",
"externalRef": "acme-cust-4471",
"reason": "Balance adjustment for data feed error"
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}"
payload = {
"metadata": {
"notes": "VIP customer",
"supportTicket": "TKT-123"
},
"mergeMetadata": True,
"status": "passed",
"initialBalance": 100000,
"currentBalance": 105000,
"highWaterMark": 107500,
"customerId": "acme-cust-4471",
"externalRef": "acme-cust-4471",
"reason": "Balance adjustment for data feed error"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
metadata: {notes: 'VIP customer', supportTicket: 'TKT-123'},
mergeMetadata: true,
status: 'passed',
initialBalance: 100000,
currentBalance: 105000,
highWaterMark: 107500,
customerId: 'acme-cust-4471',
externalRef: 'acme-cust-4471',
reason: 'Balance adjustment for data feed error'
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'metadata' => [
'notes' => 'VIP customer',
'supportTicket' => 'TKT-123'
],
'mergeMetadata' => true,
'status' => 'passed',
'initialBalance' => 100000,
'currentBalance' => 105000,
'highWaterMark' => 107500,
'customerId' => 'acme-cust-4471',
'externalRef' => 'acme-cust-4471',
'reason' => 'Balance adjustment for data feed error'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}"
payload := strings.NewReader("{\n \"metadata\": {\n \"notes\": \"VIP customer\",\n \"supportTicket\": \"TKT-123\"\n },\n \"mergeMetadata\": true,\n \"status\": \"passed\",\n \"initialBalance\": 100000,\n \"currentBalance\": 105000,\n \"highWaterMark\": 107500,\n \"customerId\": \"acme-cust-4471\",\n \"externalRef\": \"acme-cust-4471\",\n \"reason\": \"Balance adjustment for data feed error\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"notes\": \"VIP customer\",\n \"supportTicket\": \"TKT-123\"\n },\n \"mergeMetadata\": true,\n \"status\": \"passed\",\n \"initialBalance\": 100000,\n \"currentBalance\": 105000,\n \"highWaterMark\": 107500,\n \"customerId\": \"acme-cust-4471\",\n \"externalRef\": \"acme-cust-4471\",\n \"reason\": \"Balance adjustment for data feed error\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"metadata\": {\n \"notes\": \"VIP customer\",\n \"supportTicket\": \"TKT-123\"\n },\n \"mergeMetadata\": true,\n \"status\": \"passed\",\n \"initialBalance\": 100000,\n \"currentBalance\": 105000,\n \"highWaterMark\": 107500,\n \"customerId\": \"acme-cust-4471\",\n \"externalRef\": \"acme-cust-4471\",\n \"reason\": \"Balance adjustment for data feed error\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Trading account updated successfully",
"data": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"accountNumber": "ACC-MKVEUQWQ",
"type": "evaluation",
"status": "passed",
"initialBalance": 100000,
"currentBalance": 110000,
"highWaterMark": 112000,
"dailyStartingBalance": 109000,
"startedAt": "2025-01-16T09:00:00.000Z",
"completedAt": "2025-02-15T16:30:00.000Z",
"violationReason": null,
"metadata": {},
"userId": "11111111-1111-4111-8111-111111111111",
"createdAt": "2025-01-15T10:00:00.000Z",
"updatedAt": "2025-02-17T14:30:00.000Z"
}
}{
"statusCode": 400,
"error": "Bad Request",
"message": "No valid fields to update",
"code": "NO_FIELDS_TO_UPDATE"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid or expired session"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "Only organization admins can perform this action",
"code": "NOT_ADMIN"
}{
"statusCode": 404,
"error": "Not Found",
"message": "Trading account not found",
"code": "ACCOUNT_NOT_FOUND"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
"code": "IDEMPOTENCY_KEY_REUSED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"statusCode": 502,
"error": "Bad Gateway",
"message": "The trading engine did not confirm that the open positions and working orders were closed, so the status was not changed. Check the positions and send the change again.",
"code": "CLOSE_NOT_CONFIRMED",
"data": {
"accountId": "<string>"
}
}{
"statusCode": 503,
"error": "Service Unavailable",
"message": "The change was saved, but the trading engine did not confirm it yet. Send the same request again.",
"code": "ENGINE_NOT_CONFIRMED"
}Authorizations
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
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.
255Body
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).
255"acme-cust-4471"
curl --request PATCH \
--url https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"metadata": {
"notes": "VIP customer",
"supportTicket": "TKT-123"
},
"mergeMetadata": true,
"status": "passed",
"initialBalance": 100000,
"currentBalance": 105000,
"highWaterMark": 107500,
"customerId": "acme-cust-4471",
"externalRef": "acme-cust-4471",
"reason": "Balance adjustment for data feed error"
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}"
payload = {
"metadata": {
"notes": "VIP customer",
"supportTicket": "TKT-123"
},
"mergeMetadata": True,
"status": "passed",
"initialBalance": 100000,
"currentBalance": 105000,
"highWaterMark": 107500,
"customerId": "acme-cust-4471",
"externalRef": "acme-cust-4471",
"reason": "Balance adjustment for data feed error"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
metadata: {notes: 'VIP customer', supportTicket: 'TKT-123'},
mergeMetadata: true,
status: 'passed',
initialBalance: 100000,
currentBalance: 105000,
highWaterMark: 107500,
customerId: 'acme-cust-4471',
externalRef: 'acme-cust-4471',
reason: 'Balance adjustment for data feed error'
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'metadata' => [
'notes' => 'VIP customer',
'supportTicket' => 'TKT-123'
],
'mergeMetadata' => true,
'status' => 'passed',
'initialBalance' => 100000,
'currentBalance' => 105000,
'highWaterMark' => 107500,
'customerId' => 'acme-cust-4471',
'externalRef' => 'acme-cust-4471',
'reason' => 'Balance adjustment for data feed error'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}"
payload := strings.NewReader("{\n \"metadata\": {\n \"notes\": \"VIP customer\",\n \"supportTicket\": \"TKT-123\"\n },\n \"mergeMetadata\": true,\n \"status\": \"passed\",\n \"initialBalance\": 100000,\n \"currentBalance\": 105000,\n \"highWaterMark\": 107500,\n \"customerId\": \"acme-cust-4471\",\n \"externalRef\": \"acme-cust-4471\",\n \"reason\": \"Balance adjustment for data feed error\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"notes\": \"VIP customer\",\n \"supportTicket\": \"TKT-123\"\n },\n \"mergeMetadata\": true,\n \"status\": \"passed\",\n \"initialBalance\": 100000,\n \"currentBalance\": 105000,\n \"highWaterMark\": 107500,\n \"customerId\": \"acme-cust-4471\",\n \"externalRef\": \"acme-cust-4471\",\n \"reason\": \"Balance adjustment for data feed error\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"metadata\": {\n \"notes\": \"VIP customer\",\n \"supportTicket\": \"TKT-123\"\n },\n \"mergeMetadata\": true,\n \"status\": \"passed\",\n \"initialBalance\": 100000,\n \"currentBalance\": 105000,\n \"highWaterMark\": 107500,\n \"customerId\": \"acme-cust-4471\",\n \"externalRef\": \"acme-cust-4471\",\n \"reason\": \"Balance adjustment for data feed error\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Trading account updated successfully",
"data": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"accountNumber": "ACC-MKVEUQWQ",
"type": "evaluation",
"status": "passed",
"initialBalance": 100000,
"currentBalance": 110000,
"highWaterMark": 112000,
"dailyStartingBalance": 109000,
"startedAt": "2025-01-16T09:00:00.000Z",
"completedAt": "2025-02-15T16:30:00.000Z",
"violationReason": null,
"metadata": {},
"userId": "11111111-1111-4111-8111-111111111111",
"createdAt": "2025-01-15T10:00:00.000Z",
"updatedAt": "2025-02-17T14:30:00.000Z"
}
}{
"statusCode": 400,
"error": "Bad Request",
"message": "No valid fields to update",
"code": "NO_FIELDS_TO_UPDATE"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid or expired session"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "Only organization admins can perform this action",
"code": "NOT_ADMIN"
}{
"statusCode": 404,
"error": "Not Found",
"message": "Trading account not found",
"code": "ACCOUNT_NOT_FOUND"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
"code": "IDEMPOTENCY_KEY_REUSED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"statusCode": 502,
"error": "Bad Gateway",
"message": "The trading engine did not confirm that the open positions and working orders were closed, so the status was not changed. Check the positions and send the change again.",
"code": "CLOSE_NOT_CONFIRMED",
"data": {
"accountId": "<string>"
}
}{
"statusCode": 503,
"error": "Service Unavailable",
"message": "The change was saved, but the trading engine did not confirm it yet. Send the same request again.",
"code": "ENGINE_NOT_CONFIRMED"
}