> ## 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.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:** ```bash 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:** ```bash 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`, 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, quick start, error handling, idempotency, pagination, custom metadata, webhooks, and the MCP connector are documented at https://docs.hyperprop.com. 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: Trading accounts description: Create, update, and inspect trading accounts. - name: Traders description: Look up and update the traders in your organization. - name: Trading plans description: Define the plans you sell. - name: Trading rules description: Define how accounts are evaluated. - name: Lockouts description: Pause and resume trading on an account. - name: Payouts description: Check payout eligibility and record payouts. - name: Purchases description: Purchases recorded for your organization. - name: Time Machine description: Restore accounts to an earlier trading day or instant. - name: Webhooks description: Register webhook endpoints and inspect deliveries. - name: Events description: Your organization's event history and real-time event stream. - name: Reconciliation description: Balances, end-of-day snapshots, and fills for reconciliation. - name: Analytics description: Organization performance and plan economics. - name: Billing description: 'Your Hyperprop bill: activity, billing cycles, and forecasts.' - name: Team and roles description: Manage dashboard access for your staff. - name: API keys description: Manage your organization's API key. - name: Logs and health description: API request logs, the audit log, and integration health. - name: Organization profile description: Your organization's profile and logo. - name: Support description: Open and follow up on support tickets. - name: Partner access description: >- Read a trader's journal as an approved partner app, with the trader's own key. paths: /v1/organization/trading-accounts/{accountId}: patch: tags: - Trading accounts 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.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:** ```bash 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:** ```bash 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`, 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/Model904' responses: '200': description: Account updated successfully content: '*/*': schema: $ref: '#/components/schemas/Model907' '400': description: Bad Request - No valid fields to update content: '*/*': schema: $ref: '#/components/schemas/Model908' '401': description: Unauthorized - Invalid or missing API key content: '*/*': schema: $ref: '#/components/schemas/Model909' '403': description: Forbidden - Not an admin or account belongs to different org content: '*/*': schema: $ref: '#/components/schemas/Model910' '404': description: Not Found - No account exists with this ID content: '*/*': schema: $ref: '#/components/schemas/Model911' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model5' security: - X-API-Key: [] components: schemas: Model904: type: object properties: metadata: $ref: '#/components/schemas/Model902' 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/Model903' 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: acme-cust-4471 maxLength: 255 externalRef: type: string description: >- DEPRECATED alias for customerId — use customerId instead. Null is ignored (customerId cannot be cleared). example: acme-cust-4471 maxLength: 255 reason: type: string description: Reason for the change (logged in audit trail) example: Balance adjustment for data feed error Model907: type: object properties: success: type: boolean example: true message: type: string example: Trading account updated successfully data: $ref: '#/components/schemas/Model906' Model908: 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 Model909: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Invalid or expired session Model910: 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 Model911: 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 Model5: 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 Model902: type: object description: >- Custom metadata. Replaces existing metadata wholesale unless mergeMetadata is true. example: notes: VIP customer supportTicket: TKT-123 Model903: type: string description: Account status example: passed enum: - not_started - in_progress - passed - failed - expired Model906: 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/Model905' 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' Model905: type: object securitySchemes: X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key. Format: "hp_live_{key}". Organization admins manage the key in the dashboard. ```` ## Related topics - [Bulk update trading accounts](/platform-api/trading-accounts/bulk-update-trading-accounts.md) - [MCP connector (AI agents)](/guides/mcp-connector.md) - [Update a trading rule](/platform-api/trading-rules/update-a-trading-rule.md) - [Update a trading plan](/platform-api/trading-plans/update-a-trading-plan.md) - [Create or update a copy trading config](/trade-api/copy-trading/create-or-update-a-copy-trading-config.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.