Coins.ph Coins Pro — Sub-Account
Coins Pro — Sub-Account API (TRADING v1.0.0) — part of the Coins.ph developer platform.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "TRADING",
"version": "1.0.0",
"description": "Sub Account endpoints for the Coins.ph Trading API — covering Sub Account deposit addresses, deposit history, and inter-account transfers."
},
"servers": [
{
"url": "https://api.pro.coins.ph",
"description": "Production"
},
{
"url": "https://api.9001.pl-qa.coinsxyz.me",
"description": "Sandbox"
}
],
"tags": [
{
"name": "Sub Account",
"description": "Sub Account deposit, withdrawal, and transfer operations."
}
],
"x-tagGroups": [
{
"name": "TRADING",
"tags": [
"Sub Account"
]
}
],
"x-readme": {
"proxy-enabled": false
},
"paths": {
"/openapi/v1/sub-account/create": {
"post": {
"tags": [
"Sub Account"
],
"summary": "Create a Virtual Sub-account (For Master Account)",
"description": "Creates a new virtual sub-account under the master account. This interface currently supports\nthe creation of virtual sub-accounts with a maximum limit of 30 sub-accounts per master account.\nSub-accounts are useful for organizing trading activities, segregating funds, and managing\nmultiple strategies under a single master account.\n\n**Master Account Privileges**\n\n- This endpoint can only be accessed by master accounts.\n- Master accounts can create up to 30 virtual sub-accounts.\n- Each sub-account operates independently with its own balance.\n- Sub-accounts cannot create additional sub-accounts.\n\n**Sub-account Characteristics**\n\n- Virtual email addresses (may not require actual email verification).\n- Independent trading accounts under master control.\n- Cannot be deleted once created (only frozen).\n- API keys must be generated separately for each sub-account.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\n| Weight (IP) | Weight (UID) |\n|---|---|\n| 60 | 30 |\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Multi-Strategy Trading** — Separate accounts for different trading strategies.\n- **Risk Segregation** — Isolate risky strategies from main account.\n- **Team Management** — Individual accounts for team members.\n- **Testing & Development** — Separate accounts for testing strategies.\n- **Compliance & Reporting** — Separate accounts for regulatory reporting.\n\n**Best Practices**\n\n- Use descriptive email naming: `strategy1@domain.com`, `client_001@domain.com`.\n- Track all created sub-accounts in your system.\n- Implement access control for sub-account operations.\n- Regular audit of sub-account activities.\n",
"operationId": "create_virtual_sub_account",
"parameters": [
{
"in": "header",
"name": "X-COINS-APIKEY",
"required": true,
"schema": {
"type": "string",
"example": "VGkCt1GWUqWsxsCtsTvqLP7xNxOikd6wd7uPbnMIk8RUHQZ2bNd4Gcmq6NgQ6VlK"
},
"description": "API key for authentication (master account's API key)."
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"accountName",
"timestamp",
"signature"
],
"properties": {
"accountName": {
"type": "string",
"maxLength": 100,
"example": "test@coins.ph",
"description": "Email address for the sub-account. Must be a valid email format and unique across the system. This will serve as the login identifier for the sub-account.\n"
},
"recvWindow": {
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 60000,
"example": 5000,
"description": "Request validity window in milliseconds. Default: 5000, Maximum: 60000."
},
"timestamp": {
"type": "integer",
"format": "int64",
"minimum": 0,
"example": 1499827319559,
"description": "Unix timestamp in milliseconds."
},
"signature": {
"type": "string",
"example": "c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71",
"description": "HMAC SHA256 signature of the request parameters [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order)"
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "Create virtual sub-account",
"source": "curl --location --request POST 'https://api.pro.coins.ph/openapi/v1/sub-account/create' \\\n--header 'X-COINS-APIKEY: <your api key>' \\\n--data-urlencode 'accountName=test@coins.ph' \\\n--data-urlencode 'timestamp=1499827319559' \\\n--data-urlencode 'signature=<calculated_signature>'\n"
}
],
"responses": {
"200": {
"description": "Virtual sub-account created successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Sub-account email address.",
"example": "testsub@gmail.com"
},
"createTime": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in milliseconds when the sub-account was created.",
"example": 1689744700710
},
"isFreeze": {
"type": "boolean",
"description": "Freeze status. true = Frozen (trading and transfers disabled); false = Active (normal operations allowed).\n",
"example": false
}
}
},
"examples": {
"success": {
"summary": "Sub-account Created Successfully",
"value": {
"email": "testsub@gmail.com",
"createTime": 1689744700710,
"isFreeze": false
}
}
}
}
}
},
"default": {
"description": "API error response. The `code` field contains the internal API error code (not an HTTP status code).\n\n| Code | Description |\n|---|---|\n| -4003 | Sub-account already exists. |\n| -4004 | Maximum number of sub-accounts (30) reached. |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/openapi/v1/sub-account/list": {
"get": {
"tags": [
"Sub Account"
],
"summary": "Query Sub-account List (For Master Account)",
"description": "Retrieves a list of all sub-accounts associated with the master account. This endpoint applies\nto master accounts only and provides comprehensive information about each sub-account including\ncreation time, email address, and freeze status. Supports pagination for efficient handling\nof large numbers of sub-accounts.\n\n**Access Control**\n\n- This endpoint can only be accessed by master accounts.\n- Sub-accounts cannot query other sub-accounts.\n- Supports filtering by specific email address.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 10\n\n**isFreeze Field**\n\n- `false` = Active (can trade and transfer).\n- `true` = Frozen (operations blocked).\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Account Inventory** — Get complete list of all sub-accounts.\n- **Status Monitoring** — Check freeze status of all accounts.\n- **Batch Operations** — Get list before performing bulk actions.\n\n**Best Practices**\n\n- Default limit is 10 accounts per page; maximum is 200.\n- Cache results to reduce API calls (typical cache: 1–5 minutes).\n",
"operationId": "query_sub_account_list",
"parameters": [
{
"in": "header",
"name": "X-COINS-APIKEY",
"required": true,
"schema": {
"type": "string"
},
"description": "API key for authentication (master account's API key)."
},
{
"in": "query",
"name": "email",
"required": false,
"schema": {
"type": "string",
"example": "test@coins.ph"
},
"description": "Filter by specific sub-account email address. If provided, returns only the matching sub-account. If omitted, returns all sub-accounts.\n"
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"type": "integer",
"example": 1
},
"description": "Current page number for pagination. Default value: 1."
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"example": 10
},
"description": "Quantity of results per page. Default value: 10. Maximum: 200."
},
{
"in": "query",
"name": "recvWindow",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 60000
},
"description": "Request validity window in milliseconds. Default: 5000, Maximum: 60000."
},
{
"in": "query",
"name": "timestamp",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"example": 1499827319559
},
"description": "Unix timestamp in milliseconds."
},
{
"in": "query",
"name": "signature",
"required": true,
"schema": {
"type": "string"
},
"description": "HMAC SHA256 signature of the request parameters [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order)"
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "Query sub-account list (paginated)",
"source": "curl --get --location 'https://api.pro.coins.ph/openapi/v1/sub-account/list' \\\n--header 'X-COINS-APIKEY: <your api key>' \\\n--data-urlencode 'page=1' \\\n--data-urlencode 'limit=10' \\\n--data-urlencode 'timestamp=1689744700710' \\\n--data-urlencode 'signature=<calculated_signature>'\n"
}
],
"responses": {
"200": {
"description": "Sub-account list returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subAccounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"createTime": {
"type": "string",
"description": "Unix timestamp (ms) when the sub-account was created.",
"example": "1689744671462"
},
"email": {
"type": "string",
"description": "Sub-account email address.",
"example": "test@coins.ph"
},
"isFreeze": {
"type": "boolean",
"description": "false = Active (can trade and transfer); true = Frozen (operations blocked).\n",
"example": false
}
}
}
},
"total": {
"type": "integer",
"description": "Total number of sub-accounts.",
"example": 2
}
}
},
"examples": {
"success": {
"summary": "Sub-account list",
"value": {
"subAccounts": [
{
"createTime": "1689744671462",
"email": "test@coins.ph",
"isFreeze": false
},
{
"createTime": "1689744700710",
"email": "testsub2@gmail.com",
"isFreeze": false
}
],
"total": 2
}
},
"empty": {
"summary": "Empty list",
"value": {
"subAccounts": [],
"total": 0
}
}
}
}
}
},
"default": {
"description": "API error response. The `code` field contains the internal API error code (not an HTTP status code).\n\n| Code | Description |\n|---|---|\n| -1022 | Signature for this request is not valid. |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/openapi/v1/sub-account/asset": {
"get": {
"tags": [
"Sub Account"
],
"summary": "Query Sub-account Assets (For Master Account)",
"description": "Query detailed balance information of a sub-account via the master account. This endpoint\nallows master accounts to retrieve the asset holdings and balance details of their\nsub-accounts, including free and locked balances for each asset.\n\n**Access Control**\n\n- This endpoint can only be accessed by master accounts.\n- Master accounts have read-only access to sub-account balance information.\n- Cannot be used by sub-accounts to query other sub-accounts.\n\n**Balance Types**\n\n- **Free Balance** — Available for trading, withdrawals, or transfers.\n- **Locked Balance** — Reserved for open orders, pending withdrawals, or transfers.\n- **Total Balance** = Free Balance + Locked Balance.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 10\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Portfolio Management** — Monitor total holdings across sub-accounts.\n- **Risk Management** — Track locked vs free balances for liquidity planning.\n- **Compliance** — Audit trail for sub-account asset holdings.\n- **Rebalancing** — Identify sub-accounts needing asset redistribution.\n\n**Best Practices**\n\n- `email` parameter must be the exact email address of the target sub-account (case sensitive).\n- All balance values are returned as strings to preserve precision.\n- Use decimal libraries for financial calculations.\n",
"operationId": "query_sub_account_assets",
"parameters": [
{
"in": "header",
"name": "X-COINS-APIKEY",
"required": true,
"schema": {
"type": "string"
},
"description": "API key for authentication (master account's API key)."
},
{
"in": "query",
"name": "email",
"required": true,
"schema": {
"type": "string",
"example": "testsub2@gmail.com"
},
"description": "Sub-account email address."
},
{
"in": "query",
"name": "recvWindow",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 60000
},
"description": "Request validity window in milliseconds. Default: 5000, Maximum: 60000."
},
{
"in": "query",
"name": "timestamp",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"example": 1499827319559
},
"description": "Unix timestamp in milliseconds."
},
{
"in": "query",
"name": "signature",
"required": true,
"schema": {
"type": "string"
},
"description": "HMAC SHA256 signature of the request parameters [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order)"
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "Query sub-account assets",
"source": "curl --get --location 'https://api.pro.coins.ph/openapi/v1/sub-account/asset' \\\n--header 'X-COINS-APIKEY: <your api key>' \\\n--data-urlencode 'email=testsub2@gmail.com' \\\n--data-urlencode 'timestamp=1499827319559' \\\n--data-urlencode 'signature=<calculated_signature>'\n"
}
],
"responses": {
"200": {
"description": "Sub-account asset balances returned successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"balances": {
"type": "array",
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string",
"description": "Asset/token symbol (e.g., BTC, ETH, USDT).",
"example": "BTC"
},
"free": {
"type": "string",
"description": "Available balance that can be traded or transferred.",
"example": "0.05000000"
},
"locked": {
"type": "string",
"description": "Locked/frozen balance in open orders or pending operations.",
"example": "0.01000000"
}
}
}
}
}
},
"examples": {
"success": {
"summary": "Sub-account asset balances",
"value": {
"balances": [
{
"asset": "BTC",
"free": "0.05000000",
"locked": "0.01000000"
},
{
"asset": "ETH",
"free": "1.50000000",
"locked": "0.00000000"
},
{
"asset": "USDT",
"free": "1000.00000000",
"locked": "500.00000000"
}
]
}
}
}
}
}
},
"default": {
"description": "API error response. The `code` field contains the internal API error code (not an HTTP status code).\n\n| Code | Description |\n|---|---|\n| -1022 | Signature for this request is not valid. |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/openapi/v1/fund-collect/collect-from-sub-account": {
"post": {
"tags": [
"Sub Account"
],
"summary": "Collect Sub-account Assets (For Master Account)",
"description": "Collects assets from all sub-accounts and transfers them to the master account. This endpoint\ninitiates an asset collection task that aggregates balances from all sub-accounts under the\nmaster account. The collection process is asynchronous and tracked via a unique client request\nID. If there are tasks with a status of INIT, resubmission is not allowed to prevent\nduplicate operations.\n\n**How It Works**\n\n1. Master account initiates collection with a unique `clientRequestId`.\n2. System creates a collection task with status `INIT`.\n3. System iterates through all sub-accounts and transfers available assets.\n4. Task status updates to `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILED`.\n5. Process is asynchronous — poll the status endpoint to track progress.\n\n**Collection Scope**\n\n- Collects from ALL sub-accounts; cannot select specific sub-accounts.\n- Transfers ALL available (non-locked/frozen) assets.\n- Skips sub-accounts with zero balance.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 1\n\n**Status Values**\n\n| Status | Description | Next Action |\n|---|---|---|\n| INIT | Task initiated, collection in progress | Wait and poll status |\n| PROCESSING | Actively transferring assets | Wait and poll status |\n| SUCCESS | All assets collected successfully | Complete |\n| PARTIAL_SUCCESS | Some assets collected, some failed | Review failed sub-accounts |\n| FAILED | Collection completely failed | Check error, retry if needed |\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Liquidity Management** — Pool assets for large trades.\n- **Treasury Operations** — Aggregate funds for investment.\n- **Risk Management** — Centralize assets for better control.\n\n**Best Practices**\n\n- Always use UUID format for `clientRequestId`.\n- Store `clientRequestId` for later status checking; never reuse IDs.\n- Poll the records endpoint every 10 seconds for INIT/PROCESSING tasks.\n- Check if a collection task already exists before submitting.\n",
"operationId": "collect_sub_account_assets",
"parameters": [
{
"in": "header",
"name": "X-COINS-APIKEY",
"required": true,
"schema": {
"type": "string"
},
"description": "API key for authentication (master account's API key)."
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"clientRequestId",
"timestamp",
"signature"
],
"properties": {
"clientRequestId": {
"type": "string",
"maxLength": 200,
"example": "777d3f71-4715-4150-9fd1-d13246d7e02b",
"description": "Unique request identifier. Must be unique for each collection operation. Used for idempotency and tracking. Recommended format: UUID.\n"
},
"remark": {
"type": "string",
"example": "Monthly collection",
"description": "Optional remark or note for the collection operation."
},
"recvWindow": {
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 60000,
"description": "Request validity window in milliseconds. Default: 5000, Maximum: 60000."
},
"timestamp": {
"type": "integer",
"format": "int64",
"minimum": 0,
"example": 1499827319559,
"description": "Unix timestamp in milliseconds."
},
"signature": {
"type": "string",
"description": "HMAC SHA256 signature of the request parameters [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order)"
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "Initiate asset collection",
"source": "curl --location --request POST 'https://api.pro.coins.ph/openapi/v1/fund-collect/collect-from-sub-account' \\\n--header 'X-COINS-APIKEY: <your api key>' \\\n--data-urlencode 'clientRequestId=collect_001' \\\n--data-urlencode 'remark=Monthly collection' \\\n--data-urlencode 'timestamp=1499827319559' \\\n--data-urlencode 'signature=<calculated_signature>'\n"
}
],
"responses": {
"200": {
"description": "Asset collection task initiated successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"clientRequestId": {
"type": "string",
"description": "Client-provided unique request identifier.",
"example": "collect-20240115-001"
},
"status": {
"type": "string",
"description": "Task status. Possible values: INIT, PROCESSING, SUCCESS, PARTIAL_SUCCESS, FAILED.\n",
"example": "INIT"
},
"comment": {
"type": "string",
"description": "Additional information or error details. Usually empty when status is SUCCESS.",
"example": ""
}
}
},
"examples": {
"task_initiated": {
"summary": "Task Initiated (INIT)",
"value": {
"clientRequestId": "collect-20240115-001",
"status": "INIT",
"comment": ""
}
},
"task_completed": {
"summary": "Task Completed (SUCCESS)",
"value": {
"clientRequestId": "collect-20240115-001",
"status": "SUCCESS",
"comment": "All assets collected successfully"
}
},
"partial_success": {
"summary": "Partial Success",
"value": {
"clientRequestId": "collect-20240115-001",
"status": "PARTIAL_SUCCESS",
"comment": "Some sub-accounts had insufficient balance or were frozen"
}
}
}
}
}
},
"default": {
"description": "API error response. The `code` field contains the internal API error code (not an HTTP status code).\n\n| Code | Description |\n|---|---|\n| -10324 | Request repeated (duplicate clientRequestId with INIT status). |\n| -1022 | Signature for this request is not valid. |\n| -1102 | Mandatory parameter 'clientRequestId' was not sent or is empty/null. |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/openapi/v1/fund-collect/get-fund-record": {
"get": {
"tags": [
"Sub Account"
],
"summary": "Retrieve Asset Collection Records (USER_DATA)",
"description": "Retrieves asset collection records for the master account. This endpoint allows querying\nthe status and history of asset collection operations initiated via the\ncollect-from-sub-account endpoint. Supports filtering by specific clientRequestId or\npaginated browsing of all collection records. Use this endpoint to monitor the progress\nand outcome of asset collection tasks.\n\n**Response Structure**\n\n- Response is always an array, even for single record queries.\n- Empty object `{}` if no matching records found.\n- Each record contains `clientRequestId`, `status`, and `comment`.\n\n**Status Values**\n\n- `INIT` — Collection task has been initiated and is pending.\n- `PROCESSING` — Collection is actively in progress.\n- `SUCCESS` — All assets collected successfully from all sub-accounts.\n- `PARTIAL_SUCCESS` — Some assets collected, some transfers failed.\n- `FAILED` — Collection completely failed, no assets transferred.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 1\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Status Monitoring** — Query to check collection task progress.\n- **Audit Trail** — Review history of all asset collection operations.\n- **Reconciliation** — Verify completion of scheduled collections.\n\n**Best Practices**\n\n- Poll every 10 seconds for INIT/PROCESSING tasks; stop when status becomes final.\n- Cache results for final states (SUCCESS, PARTIAL_SUCCESS, FAILED).\n- Use specific `clientRequestId` queries for faster lookup.\n",
"operationId": "retrieve_asset_collection_records",
"parameters": [
{
"in": "header",
"name": "X-COINS-APIKEY",
"required": true,
"schema": {
"type": "string"
},
"description": "API key for authentication (master account's API key)."
},
{
"in": "query",
"name": "clientRequestId",
"required": false,
"schema": {
"type": "string",
"example": "09533266-1fea-11f0-8ff9-2a3efdea066c"
},
"description": "Unique request identifier used when initiating the collection. If provided, returns only the specific collection record. If omitted, returns all records with pagination.\n"
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"type": "integer",
"example": 1
},
"description": "Page number for pagination. Default value: 1."
},
{
"in": "query",
"name": "size",
"required": false,
"schema": {
"type": "integer",
"example": 100
},
"description": "Page size - number of records per page. Default: 100. Maximum: 100."
},
{
"in": "query",
"name": "recvWindow",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 60000
},
"description": "Request validity window in milliseconds. Default: 5000, Maximum: 60000."
},
{
"in": "query",
"name": "timestamp",
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coinsph/refs/heads/main/openapi/coinsph-sub-account-openapi.json