> ## 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. # Create a new trading rule > Create a new trading rule for your organization. **Admin only**. **Required fields:** - `name` - Must be unique within your organization **Optional rule parameters:** | Field | Unit | Description | Example | |-------|------|-------------|---------| | `profitTarget` | $ | Profit target to pass | 4000 | | `dailyProfit` | $ | Max daily profit cap (0 = unlimited) | 0 | | `maxProfit` | $ | Max total profit cap (0 = unlimited) | 0 | | `dailyLoss` | $ | Max loss allowed per day | 1000 | | `maxLoss` | $ | Max total loss from starting balance | 2500 | | `dailyDrawdown` | % | Max drawdown from day's starting balance | 2 | | `maxDrawdown` | % or $ | Max drawdown (unit set by `drawdownDenomination`, reference by `drawdownType`) | 5 | | `drawdownDenomination` | | percent (default) or dollars — dollars is required for zero-based accounts | percent | | `drawdownTrailCeiling` | $ | Trailing floor lock level above initial balance (null = trails forever) | 100 | | `newsTradingAllowed` etc. | bool | Display-only permission flags (news trading, microscalping, weekend/overnight holding) shown to traders; default true, not engine-enforced | true | | `drawdownType` | | How drawdown is calculated (see below) | trailing | | `consistency` | % | Consistency rule (0 = disabled) | 0 | | `maxContracts` | count | Max position size in mini-equivalent contracts | 10 | | `microConversionRatio` | count | Micros per 1 unit toward maxContracts (default 10, see below) | 5 | | `scalingPlan` | | Profit-based contract scaling tiers (see below) | { "tiers": [...] } | | `metadata` | | Custom organization data | { "version": "1.0" } | **Understanding the units:** - **Dollar values ($):** `profitTarget`, `dailyProfit`, `maxProfit`, `dailyLoss`, `maxLoss` — these are absolute dollar amounts relative to the account size. E.g., `maxLoss: 2500` means the trader can lose $2,500. - **Percentage values (%):** `dailyDrawdown`, `consistency` — always percentages. `maxDrawdown` is a percent by default, but becomes a dollar amount when `drawdownDenomination` is `dollars` (how zero-based sim-funded plans express a $1,000 trailing max loss). **Drawdown types (`drawdownType`):** | Value | Description | |-------|-------------| | `static` | Drawdown measured from **initial balance**. Never moves. (default) | | `trailing` | Drawdown trails the **high water mark in real-time**. Updates on every fill. | | `eod` | Same as trailing but only updates at **end of day** (market close). Intraday highs don't move the floor. | **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. **Example:** ```bash curl -X POST "https://api.example.com/platform/v1/organization/trading-rules" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "name": "Aggressive 100K Challenge", "description": "High risk tolerance for experienced traders", "profitTarget": 10000, "maxLoss": 5000, "maxDrawdown": 5000, "dailyLoss": 2500, "maxContracts": 15, "microConversionRatio": 5, "metadata": { "tier": "advanced", "version": "1.0" } }' ``` **Error Codes:** | Code | Description | |------|-------------| | `RULE_NAME_EXISTS` | A rule with this name already exists | | `ADMIN_REQUIRED` | Only admins can create rules | ## OpenAPI ````yaml /api-reference/openapi.json post /v1/organization/trading-rules 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: post: tags: - Organization summary: Create a new trading rule description: >- Create a new trading rule for your organization. **Admin only**. **Required fields:** - `name` - Must be unique within your organization **Optional rule parameters:** | Field | Unit | Description | Example | |-------|------|-------------|---------| | `profitTarget` | $ | Profit target to pass | 4000 | | `dailyProfit` | $ | Max daily profit cap (0 = unlimited) | 0 | | `maxProfit` | $ | Max total profit cap (0 = unlimited) | 0 | | `dailyLoss` | $ | Max loss allowed per day | 1000 | | `maxLoss` | $ | Max total loss from starting balance | 2500 | | `dailyDrawdown` | % | Max drawdown from day's starting balance | 2 | | `maxDrawdown` | % or $ | Max drawdown (unit set by `drawdownDenomination`, reference by `drawdownType`) | 5 | | `drawdownDenomination` | | percent (default) or dollars — dollars is required for zero-based accounts | percent | | `drawdownTrailCeiling` | $ | Trailing floor lock level above initial balance (null = trails forever) | 100 | | `newsTradingAllowed` etc. | bool | Display-only permission flags (news trading, microscalping, weekend/overnight holding) shown to traders; default true, not engine-enforced | true | | `drawdownType` | | How drawdown is calculated (see below) | trailing | | `consistency` | % | Consistency rule (0 = disabled) | 0 | | `maxContracts` | count | Max position size in mini-equivalent contracts | 10 | | `microConversionRatio` | count | Micros per 1 unit toward maxContracts (default 10, see below) | 5 | | `scalingPlan` | | Profit-based contract scaling tiers (see below) | { "tiers": [...] } | | `metadata` | | Custom organization data | { "version": "1.0" } | **Understanding the units:** - **Dollar values ($):** `profitTarget`, `dailyProfit`, `maxProfit`, `dailyLoss`, `maxLoss` — these are absolute dollar amounts relative to the account size. E.g., `maxLoss: 2500` means the trader can lose $2,500. - **Percentage values (%):** `dailyDrawdown`, `consistency` — always percentages. `maxDrawdown` is a percent by default, but becomes a dollar amount when `drawdownDenomination` is `dollars` (how zero-based sim-funded plans express a $1,000 trailing max loss). **Drawdown types (`drawdownType`):** | Value | Description | |-------|-------------| | `static` | Drawdown measured from **initial balance**. Never moves. (default) | | `trailing` | Drawdown trails the **high water mark in real-time**. Updates on every fill. | | `eod` | Same as trailing but only updates at **end of day** (market close). Intraday highs don't move the floor. | **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. **Example:** ```bash curl -X POST "https://api.example.com/platform/v1/organization/trading-rules" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "name": "Aggressive 100K Challenge", "description": "High risk tolerance for experienced traders", "profitTarget": 10000, "maxLoss": 5000, "maxDrawdown": 5000, "dailyLoss": 2500, "maxContracts": 15, "microConversionRatio": 5, "metadata": { "tier": "advanced", "version": "1.0" } }' ``` **Error Codes:** | Code | Description | |------|-------------| | `RULE_NAME_EXISTS` | A rule with this name already exists | | `ADMIN_REQUIRED` | Only admins can create rules | operationId: postV1OrganizationTradingrules requestBody: content: application/json: schema: $ref: '#/components/schemas/Model524' responses: '201': description: Rule created successfully content: '*/*': schema: $ref: '#/components/schemas/Model526' '400': description: Invalid request data content: '*/*': schema: $ref: '#/components/schemas/Model194' '401': description: Authentication required content: '*/*': schema: $ref: '#/components/schemas/Model7' '403': description: Forbidden - Admin access required content: '*/*': schema: $ref: '#/components/schemas/Model527' '409': description: Conflict - Rule name already exists content: '*/*': schema: $ref: '#/components/schemas/Model528' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model3' security: - Bearer: [] - X-API-Key: [] components: schemas: Model524: type: object properties: name: type: string description: Rule name (must be unique within your organization) example: Aggressive 100K Challenge description: type: string description: Rule description example: High risk tolerance rules for experienced traders profitTarget: type: number description: Profit target to pass ($) example: 10000 dailyProfit: type: number description: Max daily profit cap (0 = unlimited) example: 0 maxProfit: type: number description: Max total profit cap (0 = unlimited) example: 0 dailyLoss: type: number description: Max loss allowed per day ($) example: 2500 maxLoss: type: number description: Max total loss from starting balance ($) example: 5000 dailyDrawdown: type: number description: Max drawdown from day's starting balance ($) example: 2500 maxDrawdown: type: number description: >- Max drawdown from the reference. Percent of the reference by default (must be <= 100); a fixed dollar amount when drawdownDenomination is "dollars". example: 5 minimum: 0 drawdownType: $ref: '#/components/schemas/Model517' drawdownDenomination: $ref: '#/components/schemas/Model518' 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: >- Consistency rule % — max share of profit any single day may reach (0 = disabled). See the consistency notes for the full formula and companion fields. example: 30 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/Model519' maxContracts: type: number description: >- Max position size in mini-equivalent contracts (micros converted via microConversionRatio). 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. example: 10 microConversionRatio: type: integer description: >- How many micro contracts (MES, MNQ, ...) count as 1 unit toward maxContracts. Default 10 (CME notional ratio). Use 5 for 5-micros-per-mini plans, or 1 to count micros the same as minis. example: 10 minimum: 1 scalingPlan: $ref: '#/components/schemas/Model521' personalRiskPolicy: $ref: '#/components/schemas/Model522' metadata: $ref: '#/components/schemas/Model523' required: - name Model526: type: object properties: success: type: boolean example: true message: type: string example: Trading rule created successfully data: $ref: '#/components/schemas/Model525' Model194: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 400 error: type: string example: Bad Request message: type: string example: Invalid request data code: type: string description: Machine-readable error code — switch on this, not on message text example: BAD_REQUEST 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 Model527: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: Admin access required code: type: string example: ADMIN_REQUIRED Model528: 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 Model517: type: string description: >- How drawdown is calculated. "static" = fixed from initial balance. "trailing" = real-time from high water mark. "eod" = trailing but only updates at end of day. example: trailing default: static enum: - static - trailing - eod Model518: 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 Model519: 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 Model521: type: object description: >- Profit-based contract scaling tiers. Overrides maxContracts when set (see notes). 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 Model522: type: object description: >- Bounds on the risk controls traders set for themselves on accounts using this rule set (see notes). Omit to leave 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 Model523: type: object description: Custom metadata for your organization example: ruleVersion: '1.0' market: futures weekendHoldingAllowed: false Model525: type: object example: id: 660e8400-e29b-41d4-a716-446655440000 name: MFFU-style 50K Rules profitTarget: 3000 maxLoss: 2500 maxDrawdown: 0 drawdownType: static consistency: 50 consistencyEnforced: true consistencyBase: null consistencyTolerancePct: 0.2 consistencyLeniency: 0 consistencyMinDays: null consistencyProfitableDayMin: 0 maxPayouts: null payoutMllLockOffset: 100 metadata: tier: advanced market: futures createdAt: '2026-02-18T21:19:56.853Z' properties: id: type: string name: type: string profitTarget: type: number maxLoss: type: number maxDrawdown: type: number consistency: type: number 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) metadata: $ref: '#/components/schemas/changes' createdAt: type: string 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' changes: type: object 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 - [Create a new trading plan](/platform-api/organization/create-a-new-trading-plan.md) - [Create a trading account](/platform-api/organization/create-a-trading-account.md) - [Create or update a copy trading config](/trade-api/copy-trading/create-or-update-a-copy-trading-config.md) - [Update a trading rule](/platform-api/organization/update-a-trading-rule.md) - [Create admin lockout](/platform-api/organization/create-admin-lockout.md)