> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt > Use this file to discover all available pages before exploring further. # 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` | | `initialBalance` | Starting balance | | `currentBalance` | Current balance | | `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: ```json // 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: ```bash curl -X PATCH "https://api.example.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:** ```bash curl -X PATCH "https://api.example.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:** ```bash curl -X PATCH "https://api.example.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`, or `expired` automatically sets `completedAt` (and may end the trader's market-data entitlement) - `not_started` clears `startedAt`, `completedAt`, and `violationReason` (full reset) **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 | | 403 | `ACCOUNT_NOT_IN_ORG` | The account belongs to a different organization | | 404 | `ACCOUNT_NOT_FOUND` | No account with this ID | | 500 | `UPDATE_ACCOUNT_ERROR` | Unexpected server error | ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/organization/trading-accounts/{accountId} openapi: 3.0.0 info: title: Hyperprop Platform API version: 1.0.0 description: >- REST API for the Hyperprop Trading Platform — provision evaluation and funded trading accounts, manage traders and plans, react to account lifecycle events via signed webhooks, and reconcile billing. Built for prop firms integrating from their own backend. ## Authentication Two methods, depending on who is calling: ### Bearer Token (JWT) — users & dashboard Most endpoints accept a JWT via `Authorization: Bearer `. Used by the dashboard and client applications. ### API Key — organizations (prop firms) Organization endpoints also accept `X-API-Key: hp_live_...` for programmatic access from your backend — no browser session needed. Keys are managed by organization admins in the dashboard; each key carries permissions (`read`, `write`, `admin`) and can be rotated or revoked at any time. Keys are stored hashed (SHA-256) — the raw key is shown once at creation. Endpoints that create or modify data require `write` or `admin`. ## Quick Start ```bash # 1. List your trading plans (grab a tradingPlanId) curl "https://api.hyperprop.com/platform/v1/organization/trading-plans" \ -H "X-API-Key: hp_live_your_key_here" # 2. Create a trading account for a trader (by Hyperprop user ID or email) curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"type": "evaluation", "tradingPlanId": "", "email": "trader@example.com"}' ``` ## Response Envelope & Error Handling **Success** responses always wrap the payload: ```json { "success": true, "data": { ... }, "message": "optional human-readable note" } ``` **Errors** — including request-validation failures, auth failures, and errors proxied from the trade engine — always return this single uniform shape with a machine-readable `code` you can switch on: ```json { "success": false, "statusCode": 404, "error": "Not Found", "message": "No Hyperprop user found with that email. The trader must have a Hyperprop account before an account can be created for them.", "code": "TRADER_NOT_FOUND" } ``` Parse rule of thumb: check `success`; on `false`, switch on `code` (never on `message` text — messages can be reworded). Some errors carry additional structured context alongside these fields (e.g. payout rejections include a `consistency` block). Common codes: `VALIDATION_ERROR` (malformed payload/params), `UNAUTHORIZED`, `INSUFFICIENT_PERMISSIONS` / `NOT_ADMIN` (key lacks write/admin), `*_NOT_FOUND` (missing resource), `*_NOT_IN_ORG` (resource belongs to another organization), `IDEMPOTENCY_KEY_IN_PROGRESS` (duplicate in flight), `ENGINE_UNREACHABLE` (trade engine down — retry with the same idempotency key). Endpoint-specific codes (e.g. payout `OPEN_EXPOSURE`, `CONSISTENCY_BLOCKED`) are documented on each endpoint. ## Idempotency **Every mutating endpoint (POST, PUT, PATCH, DELETE) honors idempotency keys uniformly.** Send an `Idempotency-Key` header (the `X-Idempotency-Key` spelling is accepted as an alias) to retry any write safely without creating duplicates. How it works: - The key is scoped to your organization + the request path. The first request with a given key executes normally and its response is cached for **24 hours**. - A replay (same key, same path) within 24 hours returns the cached response with an `Idempotency-Replayed: true` response header — the operation is **not** executed again. - If a request with the same key is still in flight, the duplicate gets `409 IDEMPOTENCY_KEY_IN_PROGRESS` — back off and retry; you'll then receive the cached response. - 5xx responses are **not** cached, so retrying after a server error re-executes the request (that's what you want). 2xx-4xx responses are cached — if a request failed validation and you fix the payload, use a **fresh key**. - Keys are free-form strings up to 255 characters. Use something that identifies the operation on your side, e.g. `order-8814-attempt-1`. ```bash curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Idempotency-Key: order-8814-attempt-1" \ -H "Content-Type: application/json" \ -d '{"type": "evaluation", "tradingPlanId": "...", "traderId": "..."}' ``` This applies to account creation, account PATCH (status, currentBalance, metadata), rules, plans, lockouts, payouts, team, webhooks — every write on the platform API. Payouts additionally forward the key to the trade engine for engine-level double-withdrawal protection. ## Pagination & Sorting List endpoints support both styles: - **Cursor (recommended):** pass `?cursor=` from the previous response's `pagination.nextCursor`. Stable under concurrent writes. - **Offset:** `?limit=&offset=` with `pagination.total` / `hasMore` in the response. Sorting uses `?sort=field:direction` (e.g. `?sort=created_at:asc`); allowed fields are listed per endpoint. Default: `created_at:desc`. ## Custom Metadata Trading accounts, purchases, traders, plans, and rules all carry a free-form `metadata` JSON object. Use it to store your own references — payment IDs, campaign tags, payout records, internal notes. Hyperprop stores and returns it verbatim (and lets you filter list endpoints by it, e.g. `?metadata=stripePaymentId:pi_123`) but never interprets it. Update endpoints support `mergeMetadata: true` for shallow (top-level) merges instead of wholesale replacement. ## Webhooks Subscribe to account lifecycle events (`account.created`, `account.status_changed`, `account.updated`, `account.passed`, `account.failed`, and more) via the Webhooks endpoints. Deliveries are HMAC-SHA256 signed — verify `X-Hyperprop-Signature` with your endpoint secret, using `X-Hyperprop-Timestamp` for replay protection; `X-Hyperprop-Delivery` gives you a unique delivery ID for deduplication. Failed deliveries are retried with backoff, and you can redeliver any event from the dashboard or API. ## MCP Connector (AI Agents) The platform ships a built-in [MCP](https://modelcontextprotocol.io) server, so AI agents and assistants (Claude, Cursor, custom agents) can operate your organization directly — no integration code required. ```http Endpoint: POST https://api.hyperprop.com/platform/v1/mcp Transport: Streamable HTTP (stateless, JSON responses) Auth: X-API-Key header, Authorization: Bearer hp_live_..., or OAuth ``` **Claude web / desktop (Add custom connector):** paste the endpoint URL and leave the OAuth Client ID/Secret fields empty — the connector registers itself automatically. Claude opens a Hyperprop consent page where an org admin pastes the organization API key once; access then follows that key's permissions and ends if the key is revoked. (Under the hood: OAuth 2.1 with PKCE and dynamic client registration.) **Cursor / Claude Code — `mcp.json`:** ```json { "mcpServers": { "hyperprop": { "url": "https://api.hyperprop.com/platform/v1/mcp", "headers": { "X-API-Key": "hp_live_your_key_here" } } } } ``` **Available tools (12):** `list_trading_plans`, `list_trading_accounts`, `get_trading_account`, `get_account_audit_log`, `list_traders`, `get_trader`, `list_purchases`, `get_purchase`, `get_billing_summary` (read) · `create_trading_account`, `update_trading_account`, `record_payout` (write). Every tool call executes the corresponding REST endpoint with your key, so organization scoping, permissions, validation, audit logging, and webhooks apply exactly as documented on each endpoint. Read tools work with any key; write tools need `write`/`admin` permission — connect a **read-only key** if you want a strictly read-only agent. `create_trading_account` accepts an optional `idempotencyKey` so agent retries can't create duplicates, and `record_payout` implements the documented payout recipe (append to `metadata.payouts`, adjust `currentBalance`, audit-logged `reason`). ## Endpoint Groups - **Authentication** — Sign up, sign in, OAuth, MFA, password reset. No auth required for most. - **User** — Profile, notifications, demo accounts, audit logs. Requires **Bearer token** (JWT). - **Organization** — Trading accounts, plans, rules, traders, purchases, lockouts, billing, bulk operations, webhooks, analytics. Accepts **Bearer token** OR **API Key**. - **System** — Health checks. No auth required. x-logo: url: https://app.hyperprop.com/logo-icon.svg altText: Hyperprop href: https://hyperprop.com servers: - url: https://api.hyperprop.com/platform description: Production security: [] tags: - name: Authentication description: >- User authentication - signup, signin, signout, password reset, email verification, OAuth, and MFA - name: User description: >- User account management - profile, notifications, agreements, dismissals, and audit logs. Requires Bearer token. - name: Organization description: >- Organization management - profile, team, trading accounts, plans, and rules. Supports **dual authentication**: Bearer JWT token (dashboard users) OR X-API-Key (programmatic access). - name: Demo description: >- Demo account management - import, list, and delete demo trading accounts. Requires Bearer token. - name: Market Data description: CME futures contracts and market data. Requires Bearer token. - name: System description: System endpoints - health checks and connectivity paths: /v1/organization/trading-accounts/{accountId}: patch: tags: - Organization summary: Update a trading account description: >- 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` | | `initialBalance` | Starting balance | | `currentBalance` | Current balance | | `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: ```json // 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: ```bash curl -X PATCH "https://api.example.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:** ```bash curl -X PATCH "https://api.example.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:** ```bash curl -X PATCH "https://api.example.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`, or `expired` automatically sets `completedAt` (and may end the trader's market-data entitlement) - `not_started` clears `startedAt`, `completedAt`, and `violationReason` (full reset) **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 | | 403 | `ACCOUNT_NOT_IN_ORG` | The account belongs to a different organization | | 404 | `ACCOUNT_NOT_FOUND` | No account with this ID | | 500 | `UPDATE_ACCOUNT_ERROR` | Unexpected server error | operationId: patchV1OrganizationTradingaccountsAccountid parameters: - description: The trading account ID x-format: guid: true name: accountId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Model805' responses: '200': description: Account updated successfully content: '*/*': schema: $ref: '#/components/schemas/Model808' '400': description: Bad Request - No valid fields to update content: '*/*': schema: $ref: '#/components/schemas/Model809' '401': description: Unauthorized - Invalid or missing session token content: '*/*': schema: $ref: '#/components/schemas/Model810' '403': description: Forbidden - Not an admin or account belongs to different org content: '*/*': schema: $ref: '#/components/schemas/Model811' '404': description: Not Found - No account exists with this ID content: '*/*': schema: $ref: '#/components/schemas/Model812' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model3' security: - Bearer: [] - X-API-Key: [] components: schemas: Model805: type: object properties: metadata: $ref: '#/components/schemas/Model803' mergeMetadata: type: boolean description: >- When true, the provided metadata keys are merged into the existing metadata instead of replacing it entirely example: true status: $ref: '#/components/schemas/Model804' initialBalance: type: number description: Initial account balance example: 100000 currentBalance: type: number description: Current account balance example: 105000 highWaterMark: type: number description: Highest balance achieved example: 107500 customerId: type: string description: >- 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). example: mffu-cust-4471 maxLength: 255 externalRef: type: string description: >- DEPRECATED alias for customerId — use customerId instead. Null is ignored (customerId cannot be cleared). example: mffu-cust-4471 maxLength: 255 reason: type: string description: Reason for the change (logged in audit trail) example: Balance adjustment for data feed error Model808: type: object properties: success: type: boolean example: true message: type: string example: Trading account updated successfully data: $ref: '#/components/schemas/Model807' Model809: type: object properties: statusCode: type: number example: 400 error: type: string example: Bad Request message: type: string example: No valid fields to update code: type: string example: NO_FIELDS_TO_UPDATE Model810: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Invalid or expired session Model811: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: This account does not belong to your organization code: type: string example: ACCOUNT_NOT_IN_ORG Model812: type: object properties: statusCode: type: number example: 404 error: type: string example: Not Found message: type: string example: Trading account not found code: type: string example: ACCOUNT_NOT_FOUND Model3: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 500 error: type: string example: Internal Server Error message: type: string example: An unexpected error occurred code: type: string description: Machine-readable error code — switch on this, not on message text example: INTERNAL_ERROR Model803: type: object description: >- Custom metadata. Replaces existing metadata wholesale unless mergeMetadata is true. example: notes: VIP customer supportTicket: TKT-123 Model804: type: string description: Account status example: passed enum: - not_started - in_progress - passed - failed - expired Model807: type: object properties: id: type: string example: f47ac10b-58cc-4372-a567-0e02b2c3d479 accountNumber: type: string example: ACC-MKVEUQWQ type: type: string example: evaluation status: type: string example: passed initialBalance: type: number example: 100000 currentBalance: type: number example: 110000 highWaterMark: type: number example: 112000 dailyStartingBalance: type: number example: 109000 startedAt: type: string example: '2025-01-16T09:00:00.000Z' completedAt: type: string example: '2025-02-15T16:30:00.000Z' violationReason: type: string example: null metadata: $ref: '#/components/schemas/Model806' userId: type: string example: f994bc02-343c-4026-8a57-afc085eca8d5 createdAt: type: string example: '2025-01-15T10:00:00.000Z' updatedAt: type: string example: '2025-02-17T14:30:00.000Z' Model806: type: object securitySchemes: Bearer: type: apiKey name: Authorization in: header description: >- JWT Bearer token for user session auth. Format: "Bearer {token}". Used by User and Organization endpoints. X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key for programmatic access. Format: "hp_live_{key}". Used by Organization endpoints as an alternative to Bearer token. Keys are managed in the dashboard. ```` ## Related topics - [Bulk update trading accounts](/platform-api/organization/bulk-update-trading-accounts.md) - [MCP connector (AI agents)](/guides/mcp-connector.md) - [Update a trading rule](/platform-api/organization/update-a-trading-rule.md) - [Update a trading plan](/platform-api/organization/update-a-trading-plan.md) - [Create or update a copy trading config](/trade-api/copy-trading/create-or-update-a-copy-trading-config.md)