--- updatedAt: 2026-06-17T19:52:01.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # Enroll participants Submits a new enrollment Operation. Asynchronous. Each participant is processed independently; participant-level failures do not block the others. Idempotent on (strategy_id, `X-REQUEST-ID`). # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "zerohash API", "description": "\n### Authentication\n\nzerohash Uses HMAC SHA-256 verification to ensure the authenticity of API requests, follow instructions by link [https://docs.zerohash.com/reference/api-authentication](https://docs.zerohash.com/reference/api-authentication)\n\nDownload zerohash OpenAPI Schema as JSON\n", "version": "1.7.0" }, "servers": [ { "url": "https://api.cert.zerohash.com", "description": "Certification API server" } ], "x-readme": { "proxy-enabled": false }, "paths": { "/strategies/{strategy_id}/enroll": { "post": { "tags": [ "Trade Strategy" ], "summary": "Enroll participants", "description": "Submits a new enrollment Operation. Asynchronous. Each participant is processed independently; participant-level failures do not block the others. Idempotent on (strategy_id, `X-REQUEST-ID`).", "parameters": [ { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Timestamp" }, { "name": "strategy_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the Strategy." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTradeStrategyEnrollmentBody" } } } }, "responses": { "202": { "description": "Operation accepted and queued for processing. Body is the Operation in its initial `validating` status. Poll `GET /strategies/operations/{operation_id}` or subscribe to webhooks to observe the terminal status. On idempotent re-submission the existing Operation is returned and the status code may be `200` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeStrategyOperationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code403" } } } }, "404": { "description": "Strategy not found." }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code500" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code503" } } } } } } } }, "security": [ { "apiKey": [], "apiPassphrase": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Your API public key. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for how to obtain keys.", "in": "header", "name": "X-SCX-API-KEY" }, "apiPassphrase": { "type": "apiKey", "description": "The passphrase associated with your API key, set when the key was created.", "in": "header", "name": "X-SCX-PASSPHRASE" } }, "parameters": { "Signature": { "name": "X-SCX-SIGNED", "in": "header", "description": "HMAC-SHA256 signature of the request, base64-encoded. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for the exact signing formula.", "required": true, "schema": { "type": "string" } }, "Timestamp": { "name": "X-SCX-TIMESTAMP", "in": "header", "description": "Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.", "required": true, "schema": { "type": "string", "example": "1678901234" } } }, "schemas": { "Code400": { "type": "object", "description": "Request was rejected by validation or a downstream service. `errors` is an array of human-readable messages; each entry describes a single validation failure or business-rule violation.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "example": [ "body/amount must be >= 0", "body/asset is required" ] } } }, "Code403": { "type": "object", "description": "Authentication or authorization failed. `error` is always `true`; `message` explains which check failed (missing API key, bad signature, insufficient permission, etc.).", "required": [ "error", "message" ], "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This api key does not have write permission to this endpoint" } } }, "Code500": { "type": "object", "description": "An unexpected error occurred on the server. The request can be retried after a short delay, but the same inputs may reproduce the error.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Internal Server Error" } } }, "Code503": { "type": "object", "description": "A downstream dependency was unavailable, timed out, or returned a retryable error. Safe to retry; the response carries a `zh-allow-retry: true` header.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Service Unavailable" } } }, "CreateTradeStrategyEnrollmentBody": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "underlying_currency": { "type": "string", "example": "BTC", "description": "Underlying asset code (e.g., BTC, ETH)." }, "weight": { "type": "string", "description": "Target weight in the allocation. Decimal string in [0, 1]. Weights across an allocation set must sum to exactly 1.0; a \"0\" weight in Rebalance means \"fully exit this asset\".", "example": "0.50" } }, "required": [ "underlying_currency", "weight" ] }, "description": "Target weights for the Operation. Weights must sum to exactly 1.0; underlying_currency must be unique within the list." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "participant_code": { "type": "string", "example": "CUST01" }, "amount": { "type": "string", "description": "Decimal value serialized as a string to preserve precision.", "example": "10000.00" }, "auto_rebalance": { "type": "boolean" } }, "required": [ "participant_code", "amount", "auto_rebalance" ] } } }, "required": [ "allocations", "participants" ] }, "TradeStrategyOperationResponse": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "b1c2d3e4-f5a6-4789-bcde-f01234567890", "description": "Unique identifier (UUID v4) for the Operation." }, "strategy_id": { "type": "string", "format": "uuid", "example": "b1c2d3e4-f5a6-4789-bcde-f01234567890", "description": "Strategy the Operation runs under." }, "request_id": { "type": "string", "format": "uuid", "example": "b1c2d3e4-f5a6-4789-bcde-f01234567890", "description": "Platform's idempotency key for this Operation (the `X-REQUEST-ID` sent at submission)." }, "type": { "type": "string", "enum": [ "enrollment", "top_up", "partial_sell", "rebalance", "liquidation" ], "example": "enrollment", "description": "Operation kind." }, "status": { "type": "string", "enum": [ "validating", "pricing", "settling", "settled", "skipped", "failed" ], "example": "validating", "description": "Lifecycle status. `validating` / `pricing` / `settling` are non-terminal; `settled` / `skipped` / `failed` are terminal." }, "status_reason": { "type": "string", "example": "", "description": "Set on terminal statuses to explain the outcome. Possible values: `no_executions`, `all_skipped`, `all_rejected`, `partial_success`. Empty on non-terminal and on clean `settled`." }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "underlying_currency": { "type": "string", "example": "BTC", "description": "Underlying asset code (e.g., BTC, ETH)." }, "weight": { "type": "string", "description": "Target weight in the allocation. Decimal string in [0, 1]. Weights across an allocation set must sum to exactly 1.0; a \"0\" weight in Rebalance means \"fully exit this asset\".", "example": "0.50" } }, "required": [ "underlying_currency", "weight" ] }, "description": "Target weights for this Operation. Present for enrollment / top_up / partial_sell / rebalance; empty for liquidation." }, "created_at": { "type": "string", "format": "date-time", "description": "When the Operation was created.", "example": "2026-04-17T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the Operation was last updated.", "example": "2026-04-17T10:00:00Z" } } } } } } } } ```