> ## 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 rule > Update an existing trading rule. **Admin only**. Only provide fields you want to change. Use `null` to clear optional numeric fields. **Example - Update limits:** ```bash curl -X PATCH "https://api.example.com/platform/v1/organization/trading-rules/{ruleId}" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"maxLoss": 6000, "dailyLoss": 3000}' ``` **Example - Clear a field:** ```bash curl -X PATCH ".../{ruleId}" \ -d '{"consistency": null}' ``` **Example - Set a contract scaling plan:** ```bash curl -X PATCH ".../{ruleId}" \ -d '{"scalingPlan": {"basis": "balance", "tiers": [{"profit": 0, "maxContracts": 1}, {"profit": 1000, "maxContracts": 2}, {"profit": 3000, "maxContracts": 5.5}]}}' ``` **Example - Change the micro conversion ratio (5 micros = 1 mini):** ```bash curl -X PATCH ".../{ruleId}" \ -d '{"microConversionRatio": 5}' ``` **Micro contract conversion (`microConversionRatio`):** `maxContracts` (and scaling-plan tiers) are denominated in mini-equivalent units. Micro contracts (MES, MNQ, MGC, ...) are converted using the rule set's `microConversionRatio` — how many micros count as **1 unit** toward the limit: | Ratio | `maxContracts: 10` allows | |-------|---------------------------| | `10` (default, CME notional ratio) | 10 minis or 100 micros, or any equivalent mix | | `5` | 10 minis or 50 micros | | `1` | 10 contracts total — micros count the same as minis | E-mini and full-size contracts always count as 1 unit each; the ratio only affects micros. Omit the field (or PATCH it to `null`) to use the default 10:1 conversion. Different plans can use different ratios by pointing them at different rule sets. Enforcement is account-wide and real-time in the trade engine. Example — a plan where 5 micros equal 1 mini: ```json { "maxContracts": 10, "microConversionRatio": 5 } ``` **Scaling plans (`scalingPlan`):** ## Position limits: pick the right field `maxContracts` counts **engine units** and a rule is not tied to a market, so one unit is one futures contract but **0.001 BTC** on the Binance perpetual. The same number therefore means different things depending on which account the rule backs. Use `maxPositionByMarket` for anything that is not plain futures: ```json { "name": "50K BTC Perp", "maxLoss": 2000, "dailyLoss": 1000, "maxPositionByMarket": { "BINANCE": 0.5 } } ``` That is **half a Bitcoin** — no conversion, no engine units. Rejections quote it back the same way: > Order would exceed the BINANCE position limit on this account: 0.600 BTC > requested, limit 0.500 BTC. | Field | Counts in | Scope | Use for | |---|---|---|---| | `maxPositionByMarket` | the market's own unit (BTC) | that market only | crypto, and any fractional contract | | `maxContracts` | mini-equivalents (micros via `microConversionRatio`) | all instruments | futures | A market named in `maxPositionByMarket` is **not** also gated by `maxContracts` — a market gets one limit or the other. Send `null` to clear every per-market limit and put all markets back under `maxContracts`. Instead of a flat `maxContracts` limit, you can define profit-based tiers that grow the trader's position size as they make profit: ```json { "scalingPlan": { "basis": "balance", "tiers": [ { "profit": 0, "maxContracts": 1 }, { "profit": 1000, "maxContracts": 2 }, { "profit": 3000, "maxContracts": 5.5 } ] } } ``` - `profit` is in dollars relative to the account's starting balance. The first tier must be `0` — it defines the starting limit. - Alternatively, tiers can use absolute `balance` thresholds instead of `profit` (all tiers must use the same key). The first tier defines the starting limit — set its threshold at (or below) the account size: ```json { "tiers": [ { "balance": 50000, "maxContracts": 1 }, { "balance": 55000, "maxContracts": 2 }, { "balance": 60000, "maxContracts": 5.5 } ] } ``` Note: balance thresholds tie the rule to one account size — a `55000` tier means something very different on a 25K vs 100K account. Profit-based tiers are portable across account sizes; prefer them unless all accounts on this rule share one size. - `maxContracts` is in **mini-equivalent** units and supports **0.1 steps**. Micros count as 1/`microConversionRatio` of a mini (default 10), so `5.5` allows 5 minis or 55 micros (e.g. 5 ES or 55 MES) at the default ratio. - `basis` controls when tiers activate/deactivate: | Value | Behavior | |-------|----------| | `balance` | Measured against current balance — limits scale back down if the balance drops below a threshold (default) | | `high_water_mark` | Measured against the best balance reached — tiers unlock permanently | - When `scalingPlan` is set it **overrides** `maxContracts`. Remove it (`"scalingPlan": null` on PATCH) to fall back to the flat limit. - Enforced in real time at order placement by the trade engine. **Consistency rule (`consistency` + related fields):** Caps how much of a trader's profit may come from a single day. The daily cap is: ```text daily_cap = round(base × consistency%, 2) + starting_balance × consistencyTolerancePct% + consistencyLeniency ``` A day whose net PnL **reaches or exceeds** the cap fails the rule (the boundary is inclusive). The formula is selected automatically by account type: - **Evaluation accounts** — the rule gates *passing*: base defaults to max(profitTarget, totalPnl), and the trader also needs at least `consistencyMinDays` profitable days (default: ceil(100/consistency), so 50% → 2 days). Reaching the profit target with over-concentrated gains does NOT fail the account — it simply stays active until gains are spread out, and the account's `completionPendingReason` explains exactly why. - **Sim-funded accounts** — the rule gates *payouts*: base is the profit in the current payout cycle (since the last payout with `consistencyReset`). **Enforcement is opt-in per rule set** (`consistencyEnforced`, default false — the historical behavior where the consistency % was informational only). Existing accounts are unaffected until you enable it. Example — MFFU-style template: `{ "consistency": 50, "consistencyEnforced": true, "consistencyTolerancePct": 0.2 }` on evaluation rules, and `{ "consistency": 50, "consistencyEnforced": true, "consistencyLeniency": 40 }` on Builder sim-funded rules. **Sim-funded accounts — limits are optional per rule set:** Every trading limit on a rule set applies to `sim_funded` accounts exactly like evaluations **when set**, and is disabled when `0`/omitted — so you choose per template who enforces funded limits: - **Platform enforces** (recommended): attach a rule set with real values, e.g. `{ "dailyLoss": 1500, "maxLoss": 2500, "maxContracts": 5, "consistency": 50, "consistencyEnforced": true, "consistencyLeniency": 40, "maxPayouts": 5, "payoutMllLockOffset": 100 }` — we enforce limits live, gate payouts on consistency, and fire the webhooks. - **You enforce**: attach a permissive rule set (limits `0`) and run your own logic; we still execute trades and payouts. `profitTarget` never completes a sim-funded account — funded accounts withdraw, they don't "pass" — so it is safe to reuse an eval-style rule set on funded accounts. **Warning:** Changing rules affects how accounts using these rules are evaluated. Changes apply to future evaluations, not retroactively. **Error Codes:** | Code | Description | |------|-------------| | `RULE_NOT_FOUND` | No rule exists with this ID | | `RULE_NOT_IN_ORG` | Rule belongs to a different organization | | `RULE_NAME_EXISTS` | Another rule already has this name | | `NO_FIELDS_TO_UPDATE` | No valid fields provided | | `ADMIN_REQUIRED` | Only admins can update rules | ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/organization/trading-rules/{ruleId} 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-rules/{ruleId}: patch: tags: - Organization summary: Update a trading rule description: >- Update an existing trading rule. **Admin only**. Only provide fields you want to change. Use `null` to clear optional numeric fields. **Example - Update limits:** ```bash curl -X PATCH "https://api.example.com/platform/v1/organization/trading-rules/{ruleId}" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"maxLoss": 6000, "dailyLoss": 3000}' ``` **Example - Clear a field:** ```bash curl -X PATCH ".../{ruleId}" \ -d '{"consistency": null}' ``` **Example - Set a contract scaling plan:** ```bash curl -X PATCH ".../{ruleId}" \ -d '{"scalingPlan": {"basis": "balance", "tiers": [{"profit": 0, "maxContracts": 1}, {"profit": 1000, "maxContracts": 2}, {"profit": 3000, "maxContracts": 5.5}]}}' ``` **Example - Change the micro conversion ratio (5 micros = 1 mini):** ```bash curl -X PATCH ".../{ruleId}" \ -d '{"microConversionRatio": 5}' ``` **Micro contract conversion (`microConversionRatio`):** `maxContracts` (and scaling-plan tiers) are denominated in mini-equivalent units. Micro contracts (MES, MNQ, MGC, ...) are converted using the rule set's `microConversionRatio` — how many micros count as **1 unit** toward the limit: | Ratio | `maxContracts: 10` allows | |-------|---------------------------| | `10` (default, CME notional ratio) | 10 minis or 100 micros, or any equivalent mix | | `5` | 10 minis or 50 micros | | `1` | 10 contracts total — micros count the same as minis | E-mini and full-size contracts always count as 1 unit each; the ratio only affects micros. Omit the field (or PATCH it to `null`) to use the default 10:1 conversion. Different plans can use different ratios by pointing them at different rule sets. Enforcement is account-wide and real-time in the trade engine. Example — a plan where 5 micros equal 1 mini: ```json { "maxContracts": 10, "microConversionRatio": 5 } ``` **Scaling plans (`scalingPlan`):** ## Position limits: pick the right field `maxContracts` counts **engine units** and a rule is not tied to a market, so one unit is one futures contract but **0.001 BTC** on the Binance perpetual. The same number therefore means different things depending on which account the rule backs. Use `maxPositionByMarket` for anything that is not plain futures: ```json { "name": "50K BTC Perp", "maxLoss": 2000, "dailyLoss": 1000, "maxPositionByMarket": { "BINANCE": 0.5 } } ``` That is **half a Bitcoin** — no conversion, no engine units. Rejections quote it back the same way: > Order would exceed the BINANCE position limit on this account: 0.600 BTC > requested, limit 0.500 BTC. | Field | Counts in | Scope | Use for | |---|---|---|---| | `maxPositionByMarket` | the market's own unit (BTC) | that market only | crypto, and any fractional contract | | `maxContracts` | mini-equivalents (micros via `microConversionRatio`) | all instruments | futures | A market named in `maxPositionByMarket` is **not** also gated by `maxContracts` — a market gets one limit or the other. Send `null` to clear every per-market limit and put all markets back under `maxContracts`. Instead of a flat `maxContracts` limit, you can define profit-based tiers that grow the trader's position size as they make profit: ```json { "scalingPlan": { "basis": "balance", "tiers": [ { "profit": 0, "maxContracts": 1 }, { "profit": 1000, "maxContracts": 2 }, { "profit": 3000, "maxContracts": 5.5 } ] } } ``` - `profit` is in dollars relative to the account's starting balance. The first tier must be `0` — it defines the starting limit. - Alternatively, tiers can use absolute `balance` thresholds instead of `profit` (all tiers must use the same key). The first tier defines the starting limit — set its threshold at (or below) the account size: ```json { "tiers": [ { "balance": 50000, "maxContracts": 1 }, { "balance": 55000, "maxContracts": 2 }, { "balance": 60000, "maxContracts": 5.5 } ] } ``` Note: balance thresholds tie the rule to one account size — a `55000` tier means something very different on a 25K vs 100K account. Profit-based tiers are portable across account sizes; prefer them unless all accounts on this rule share one size. - `maxContracts` is in **mini-equivalent** units and supports **0.1 steps**. Micros count as 1/`microConversionRatio` of a mini (default 10), so `5.5` allows 5 minis or 55 micros (e.g. 5 ES or 55 MES) at the default ratio. - `basis` controls when tiers activate/deactivate: | Value | Behavior | |-------|----------| | `balance` | Measured against current balance — limits scale back down if the balance drops below a threshold (default) | | `high_water_mark` | Measured against the best balance reached — tiers unlock permanently | - When `scalingPlan` is set it **overrides** `maxContracts`. Remove it (`"scalingPlan": null` on PATCH) to fall back to the flat limit. - Enforced in real time at order placement by the trade engine. **Consistency rule (`consistency` + related fields):** Caps how much of a trader's profit may come from a single day. The daily cap is: ```text daily_cap = round(base × consistency%, 2) + starting_balance × consistencyTolerancePct% + consistencyLeniency ``` A day whose net PnL **reaches or exceeds** the cap fails the rule (the boundary is inclusive). The formula is selected automatically by account type: - **Evaluation accounts** — the rule gates *passing*: base defaults to max(profitTarget, totalPnl), and the trader also needs at least `consistencyMinDays` profitable days (default: ceil(100/consistency), so 50% → 2 days). Reaching the profit target with over-concentrated gains does NOT fail the account — it simply stays active until gains are spread out, and the account's `completionPendingReason` explains exactly why. - **Sim-funded accounts** — the rule gates *payouts*: base is the profit in the current payout cycle (since the last payout with `consistencyReset`). **Enforcement is opt-in per rule set** (`consistencyEnforced`, default false — the historical behavior where the consistency % was informational only). Existing accounts are unaffected until you enable it. Example — MFFU-style template: `{ "consistency": 50, "consistencyEnforced": true, "consistencyTolerancePct": 0.2 }` on evaluation rules, and `{ "consistency": 50, "consistencyEnforced": true, "consistencyLeniency": 40 }` on Builder sim-funded rules. **Sim-funded accounts — limits are optional per rule set:** Every trading limit on a rule set applies to `sim_funded` accounts exactly like evaluations **when set**, and is disabled when `0`/omitted — so you choose per template who enforces funded limits: - **Platform enforces** (recommended): attach a rule set with real values, e.g. `{ "dailyLoss": 1500, "maxLoss": 2500, "maxContracts": 5, "consistency": 50, "consistencyEnforced": true, "consistencyLeniency": 40, "maxPayouts": 5, "payoutMllLockOffset": 100 }` — we enforce limits live, gate payouts on consistency, and fire the webhooks. - **You enforce**: attach a permissive rule set (limits `0`) and run your own logic; we still execute trades and payouts. `profitTarget` never completes a sim-funded account — funded accounts withdraw, they don't "pass" — so it is safe to reuse an eval-style rule set on funded accounts. **Warning:** Changing rules affects how accounts using these rules are evaluated. Changes apply to future evaluations, not retroactively. **Error Codes:** | Code | Description | |------|-------------| | `RULE_NOT_FOUND` | No rule exists with this ID | | `RULE_NOT_IN_ORG` | Rule belongs to a different organization | | `RULE_NAME_EXISTS` | Another rule already has this name | | `NO_FIELDS_TO_UPDATE` | No valid fields provided | | `ADMIN_REQUIRED` | Only admins can update rules | operationId: patchV1OrganizationTradingrulesRuleid parameters: - description: The rule ID to update x-format: guid: true name: ruleId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Model827' responses: '200': description: Rule updated successfully content: '*/*': schema: $ref: '#/components/schemas/Model829' '400': description: Bad Request - No valid fields to update content: '*/*': schema: $ref: '#/components/schemas/Model830' '401': description: Authentication required content: '*/*': schema: $ref: '#/components/schemas/Model7' '403': description: Forbidden - Admin required or rule not in org content: '*/*': schema: $ref: '#/components/schemas/Model831' '404': description: Not Found - Rule not found content: '*/*': schema: $ref: '#/components/schemas/Model832' '409': description: Conflict - Rule name already exists content: '*/*': schema: $ref: '#/components/schemas/Model833' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model3' security: - Bearer: [] - X-API-Key: [] components: schemas: Model827: type: object properties: name: type: string description: New rule name (must be unique) example: Updated Rule Name description: type: string description: New description (null to clear) example: Updated description profitTarget: type: number description: New profit target example: 12000 dailyProfit: type: number description: New daily profit cap maxProfit: type: number description: New max profit cap dailyLoss: type: number description: New daily loss limit example: 3000 maxLoss: type: number description: New max loss limit example: 6000 dailyDrawdown: type: number description: New daily drawdown limit maxDrawdown: type: number description: New max drawdown limit drawdownType: $ref: '#/components/schemas/Model821' drawdownDenomination: $ref: '#/components/schemas/Model822' drawdownTrailCeiling: type: number description: >- For trailing drawdowns: the floor stops climbing once it reaches initialBalance + this many dollars and locks there (the "ceiling"). Example: 100 on a $0 sim funded locks the floor at +$100 once equity has peaked $1,100. null/absent = the floor trails forever. example: 100 newsTradingAllowed: type: boolean description: >- Display-only permission flag shown to traders: trading during news events (default true). Not engine-enforced. example: true microscalpingAllowed: type: boolean description: >- Display-only permission flag shown to traders: microscalping (default true). Not engine-enforced. example: true weekendHoldingAllowed: type: boolean description: >- Display-only permission flag shown to traders: holding positions over the weekend (default true). Not engine-enforced. example: true overnightHoldingAllowed: type: boolean description: >- Display-only permission flag shown to traders: holding positions overnight (default true). Not engine-enforced. example: true consistency: type: number description: New consistency requirement (% — see consistency notes) consistencyEnforced: type: boolean description: >- Opt-in enforcement switch. false (default) = consistency % is informational only. true = the engine gates evaluation completion (evaluation accounts) or payout eligibility (sim_funded accounts) on the consistency rule. example: true consistencyBase: $ref: '#/components/schemas/consistencyBase' consistencyTolerancePct: type: number description: >- Daily-cap buffer as a percent of starting balance, added on top of base × consistency%. Example: 0.2 = $100 buffer on a $50,000 account. example: 0.2 minimum: 0 consistencyLeniency: type: number description: >- Flat dollar buffer added to the daily cap (e.g. 40 = $40 leniency on funded payout consistency). example: 40 minimum: 0 consistencyMinDays: type: integer description: >- Minimum profitable days required to pass an evaluation. null (default) = automatic ceil(100 / consistency), e.g. 50% → 2 days, 40% → 3 days. 0 = disabled. example: 2 minimum: 0 consistencyProfitableDayMin: type: number description: >- A trading day counts as profitable when its net PnL is at least this many dollars. Default 0 (any non-negative traded day counts). example: 0 minimum: 0 maxPayouts: type: integer description: >- When set, the Nth processed payout fires the account.max_payouts_reached webhook (e.g. "trader goes live after 5 payouts"). null = unlimited. example: 5 minimum: 1 payoutMllLockOffset: type: number description: >- Default loss-floor offset used by payouts requesting move_mll_to_lock: floor = initial balance + offset. Can be overridden per payout with lockBalance. example: 100 minimum: 0 maxPositionByMarket: $ref: '#/components/schemas/Model823' maxContracts: type: number description: >- New max contracts limit (mini-equivalent units). A rule is not tied to a market, so this is always counted in ENGINE units: one unit is one futures contract, but 0.001 BTC on the Binance perpetual. A 0.1 BTC cap is therefore `100`, and 1 BTC is `1000`. Read `quantityStep` on the contract to convert. microConversionRatio: type: integer description: >- How many micros count as 1 unit toward maxContracts (null resets to the default 10) example: 5 minimum: 1 scalingPlan: $ref: '#/components/schemas/Model824' personalRiskPolicy: $ref: '#/components/schemas/Model825' metadata: $ref: '#/components/schemas/Model826' mergeMetadata: type: boolean description: >- When true, the provided metadata keys are merged into the existing metadata instead of replacing it entirely example: true Model829: type: object properties: success: type: boolean example: true message: type: string example: Trading rule updated successfully data: $ref: '#/components/schemas/Model828' Model830: 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 Model7: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication required code: type: string description: Machine-readable error code — switch on this, not on message text example: UNAUTHORIZED Model831: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: This rule does not belong to your organization code: type: string example: RULE_NOT_IN_ORG Model832: type: object properties: statusCode: type: number example: 404 error: type: string example: Not Found message: type: string example: Trading rule not found code: type: string example: RULE_NOT_FOUND Model833: type: object properties: statusCode: type: number example: 409 error: type: string example: Conflict message: type: string example: A trading rule with this name already exists code: type: string example: RULE_NAME_EXISTS 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 Model821: type: string description: Change drawdown calculation method enum: - static - trailing - eod Model822: type: string description: >- Unit of maxDrawdown. "percent" (default) = % of the reference. "dollars" = a fixed dollar amount below the reference — required for zero-based (e.g. $0 sim funded) accounts, where any percent of $0 is a $0 floor. Example: drawdownType "trailing" + denomination "dollars" + maxDrawdown 1000 = a $1,000 trailing max loss whose floor starts at -$1,000. example: percent enum: - percent - dollars consistencyBase: type: string description: >- What the consistency % applies to. null (default) = automatic by account type: evaluation → max_target_or_pnl (cap grows once total PnL exceeds the target), sim_funded → cycle_profit (profit since the last consistency reset). max_profit_target_or_pnl is accepted as an alias of max_target_or_pnl. example: max_target_or_pnl enum: - max_target_or_pnl - max_profit_target_or_pnl - total_pnl - profit_target - cycle_profit Model823: type: object description: >- Per-market position limits **in each market's own unit** — `{"BINANCE": 0.5}` is half a Bitcoin, not 500 of anything. A market listed here is measured against this limit instead of `maxContracts`, so it is never gated twice; markets left out fall back to `maxContracts` in mini-equivalents. Prefer this over `maxContracts` for any market whose contract steps fractionally. example: BINANCE: 0.5 Model824: type: object description: >- New scaling plan (replaces existing; null to remove and fall back to maxContracts) example: basis: balance tiers: - profit: 0 maxContracts: 1 - profit: 1000 maxContracts: 2 - profit: 3000 maxContracts: 5.5 properties: basis: $ref: '#/components/schemas/basis' tiers: $ref: '#/components/schemas/tiers' required: - tiers Model825: type: object description: >- Replaces the existing personal risk policy in full; null removes it and leaves traders unconstrained. example: dailyLossLimitMax: 1000 dailyLossLimitDefault: 500 requireDailyLossLimit: true maxTradesPerDayMax: 20 properties: dailyLossLimitMax: type: number description: >- Ceiling on a trader's personal daily loss limit, in dollars. If the trader sets none, this value (or dailyLossLimitDefault) becomes their limit. example: 1000 x-constraint: sign: positive dailyLossLimitDefault: type: number description: >- Seeded personal daily loss limit for traders who have not chosen one. Must not exceed dailyLossLimitMax. example: 500 x-constraint: sign: positive requireDailyLossLimit: type: boolean description: >- Traders must have a personal daily loss limit, and it must be armed (an action other than do_nothing). example: true maxTradesPerDayMax: type: integer description: >- Ceiling on the trades-per-day limit a trader may set. A trade is one position open. example: 20 x-constraint: sign: positive maxTradesPerWeekMax: type: integer description: Ceiling on the trades-per-week limit a trader may set. example: 60 x-constraint: sign: positive requireAutoBracket: type: boolean description: Traders cannot switch automatic TP/SL brackets off. example: false lockedByFirm: type: boolean description: >- Freeze personal risk settings entirely — traders can view but not change them. example: false Model826: type: object description: >- New metadata. Replaces existing metadata wholesale unless mergeMetadata is true. example: version: '2.0' Model828: type: object properties: id: type: string example: 660e8400-e29b-41d4-a716-446655440000 name: type: string example: Updated Rule Name profitTarget: type: number example: 12000 maxLoss: type: number example: 6000 consistency: type: number example: 50 consistencyEnforced: type: boolean description: >- Whether the engine enforces the consistency rule for accounts on this rule set consistencyBase: type: string description: Configured base mode (null = automatic by account type) consistencyTolerancePct: type: number description: Daily-cap buffer as % of starting balance consistencyLeniency: type: number description: Flat $ daily-cap buffer consistencyMinDays: type: number description: Min profitable days (null = auto ceil(100/consistency)) consistencyProfitableDayMin: type: number description: Min net PnL ($) for a day to count as profitable maxPayouts: type: number description: >- Payout count that triggers account.max_payouts_reached (null = unlimited) payoutMllLockOffset: type: number description: Default move_mll_to_lock offset ($ above initial balance) updatedAt: type: string example: '2025-02-17T14:30:00.000Z' basis: type: string description: >- What profit is measured against. "balance" = current balance (tiers scale back down after losses). "high_water_mark" = best balance reached (tiers unlock permanently). default: balance enum: - balance - high_water_mark tiers: type: array description: >- Tiers in ascending threshold order, all using the same key (all profit or all balance). The first tier defines the starting limit; in profit mode it must be 0. minItems: 1 items: $ref: '#/components/schemas/Model520' Model520: type: object properties: profit: type: number description: >- Profit threshold in $ relative to starting balance (e.g. 1000). Each tier uses either profit or balance, not both. minimum: 0 balance: type: number description: >- Absolute balance threshold in $ (e.g. 51000). Each tier uses either profit or balance, not both. x-constraint: greater: 0 maxContracts: type: number description: >- Max position size in mini-equivalent contracts once this tier is active. 0.1 steps allowed, e.g. 5.5 = 5 minis or 55 micros at the default 10:1 microConversionRatio. On a market whose contract steps fractionally (the BTCUSDT perpetual steps 0.001 BTC) this counts ENGINE units, so 100 is 0.1 BTC and 1000 is 1 BTC — read `quantityStep` on the contract rather than assuming one unit is one coin. x-constraint: greater: 0 required: - maxContracts 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 - [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) - [Create a new trading rule](/platform-api/organization/create-a-new-trading-rule.md) - [Get trading rules for your organization](/platform-api/organization/get-trading-rules-for-your-organization.md) - [Get a specific trading rule](/platform-api/organization/get-a-specific-trading-rule.md)