> ## 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. # Get trading plans for your organization > Retrieve all trading plans configured for your organization. **What is a trading plan?** A trading plan defines the product you sell to traders. It includes the account size, price, duration, and which trading rules apply. Think of it as your "evaluation challenge" or "funded account" offering. **What you get for each plan:** - Plan details (name, description, price, currency) - Account size and evaluation duration - Default trading rules (profit target, max loss, drawdown limits) - Active/inactive status - Custom metadata (any JSON data you need) **Example plans:** - "50K Challenge" - $299, 30 days, $50,000 account - "100K Challenge" - $499, 30 days, $100,000 account - "200K Pro" - $999, 45 days, $200,000 account **Filtering by metadata:** Filter plans by any key:value in your metadata: ```http # Find plans for beginners GET /organization/trading-plans?metadata=targetAudience:beginner # Find promotional plans GET /organization/trading-plans?metadata=promo:true # Find plans by internal code GET /organization/trading-plans?metadata=internalCode:PLAN-100K ``` Supports strings, numbers, and booleans. Uses fast GIN index. **Filtering archived plans:** By default all plans are returned, including archived ones (`isActive: false`). For plan pickers and storefronts, request only live plans: ```http GET /organization/trading-plans?isActive=true ``` **Use cases:** - Display available plans on your website - Validate plan IDs before creating accounts - Check which rules are attached to each plan - Audit your product offerings ## OpenAPI ````yaml /api-reference/openapi.json get /v1/organization/trading-plans 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-plans: get: tags: - Organization summary: Get trading plans for your organization description: >- Retrieve all trading plans configured for your organization. **What is a trading plan?** A trading plan defines the product you sell to traders. It includes the account size, price, duration, and which trading rules apply. Think of it as your "evaluation challenge" or "funded account" offering. **What you get for each plan:** - Plan details (name, description, price, currency) - Account size and evaluation duration - Default trading rules (profit target, max loss, drawdown limits) - Active/inactive status - Custom metadata (any JSON data you need) **Example plans:** - "50K Challenge" - $299, 30 days, $50,000 account - "100K Challenge" - $499, 30 days, $100,000 account - "200K Pro" - $999, 45 days, $200,000 account **Filtering by metadata:** Filter plans by any key:value in your metadata: ```http # Find plans for beginners GET /organization/trading-plans?metadata=targetAudience:beginner # Find promotional plans GET /organization/trading-plans?metadata=promo:true # Find plans by internal code GET /organization/trading-plans?metadata=internalCode:PLAN-100K ``` Supports strings, numbers, and booleans. Uses fast GIN index. **Filtering archived plans:** By default all plans are returned, including archived ones (`isActive: false`). For plan pickers and storefronts, request only live plans: ```http GET /organization/trading-plans?isActive=true ``` **Use cases:** - Display available plans on your website - Validate plan IDs before creating accounts - Check which rules are attached to each plan - Audit your product offerings operationId: getV1OrganizationTradingplans parameters: - description: Filter by metadata key:value (e.g., "priority:high", "active:true") name: metadata in: query required: false schema: type: string - description: >- Filter by active status. Use isActive=true to exclude archived plans, isActive=false for archived only. Omit to get all plans. name: isActive in: query required: false schema: type: boolean - description: 'Results per page (default: 50, max: 100)' name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - description: Pagination offset name: offset in: query schema: type: integer minimum: 0 default: 0 - description: >- Cursor for pagination. Pass the `nextCursor` value from the previous response to get the next page. When using cursor, do not send `offset` — it will be ignored. **How it works:** The cursor is an opaque string that points to the last item you received. The server uses it to efficiently fetch the next set of results without scanning previous pages. **Backwards compatible:** If you don't send a cursor, offset/limit pagination works as before. name: cursor in: query required: false schema: type: string responses: '200': description: Success - Returns all trading plans content: '*/*': schema: $ref: '#/components/schemas/Model131' '401': description: Unauthorized - Invalid or missing session token content: '*/*': schema: $ref: '#/components/schemas/Model132' '403': description: Forbidden - Your account is not associated with an organization content: '*/*': schema: $ref: '#/components/schemas/Model133' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model3' security: - Bearer: [] - X-API-Key: [] components: schemas: Model131: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Model130' Model132: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Invalid or expired session Model133: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: This endpoint is only available for organization users code: type: string example: NOT_ORGANIZATION_USER 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 Model130: type: object example: organizationId: a6fcc0ce-eb28-4f43-b256-96a3144b0d34 organizationName: FakePropFirm plans: - id: 09c93da5-f057-4cc5-82da-ff9220292c94 name: 50K Challenge description: >- Our most popular evaluation. Standard risk rules with a solid balance of target and protection. price: 299 currency: USD durationDays: 30 accountSize: 50000 isActive: true metadata: targetAudience: beginner internalCode: PLAN-50K-V2 tradingRule: id: 6bec94a1-425b-47be-bb41-a80e3140e2e7 name: Standard Rules profitTarget: 4000 dailyLoss: 1000 maxLoss: 2500 maxDrawdown: 5 drawdownType: static createdAt: '2025-12-30T12:28:04.204Z' updatedAt: '2025-12-30T12:28:04.204Z' - id: d838c81a-b343-4984-aba2-f8ced8877192 name: 100K Pro description: For experienced traders ready for a bigger challenge. price: 499 currency: USD durationDays: 45 accountSize: 100000 isActive: true metadata: targetAudience: experienced internalCode: PLAN-100K-V1 tradingRule: id: 6cf3821e-0ad4-427f-85a5-c3d498aa342e name: Aggressive Rules profitTarget: 10000 dailyLoss: 3000 maxLoss: 6000 maxDrawdown: 6 drawdownType: trailing createdAt: '2026-02-18T21:19:57.328Z' updatedAt: '2026-02-18T21:19:57.328Z' pagination: total: 5 limit: 50 offset: 0 hasMore: false properties: organizationId: type: string description: Your organization ID organizationName: type: string description: Your organization name plans: $ref: '#/components/schemas/plans' pagination: $ref: '#/components/schemas/Model129' plans: type: array description: Array of trading plans items: $ref: '#/components/schemas/Model128' Model129: type: object description: Pagination info properties: total: type: number description: Total number of plans limit: type: number description: Results per page offset: type: number description: Current offset hasMore: type: boolean description: Whether more results exist nextCursor: type: string description: >- Cursor for the next page. Pass as ?cursor= to get the next set of results. Null if no more results. Model128: type: object properties: id: type: string description: Unique plan ID (use this when creating accounts) name: type: string description: Plan display name description: type: string description: Plan description for marketing price: type: number description: Plan price currency: type: string description: Price currency durationDays: type: number description: Evaluation period in days (null = unlimited) accountSize: type: number description: Starting account balance isActive: type: boolean description: Whether this plan can be purchased metadata: $ref: '#/components/schemas/Model126' tradingRule: $ref: '#/components/schemas/Model127' createdAt: type: string updatedAt: type: string Model126: type: object description: Custom metadata Model127: type: object description: Default trading rules for this plan properties: id: type: string name: type: string profitTarget: type: number description: Profit needed to pass ($) dailyLoss: type: number description: Max daily loss limit ($) maxLoss: type: number description: Max total loss limit ($) maxDrawdown: type: number description: Max drawdown (%) 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 - [Get a specific trading plan](/platform-api/organization/get-a-specific-trading-plan.md) - [Get purchases for your organization](/platform-api/organization/get-purchases-for-your-organization.md) - [Get trading accounts for your organization](/platform-api/organization/get-trading-accounts-for-your-organization.md) - [Get trading rules for your organization](/platform-api/organization/get-trading-rules-for-your-organization.md) - [Quickstart](/quickstart.md)