Coins.ph Sub Account API
Sub Account deposit, withdrawal, and transfer operations.
OpenAPI Specification
openapi: 3.0.0
info:
title: TRADING Account Sub Account API
version: 1.0.0
description: API reference for Account management — Coins.ph
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.
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
the creation of virtual sub-accounts with a maximum limit of 30 sub-accounts per master account.
Sub-accounts are useful for organizing trading activities, segregating funds, and managing
multiple strategies under a single master account.
**Master Account Privileges**
- This endpoint can only be accessed by master accounts.
- Master accounts can create up to 30 virtual sub-accounts.
- Each sub-account operates independently with its own balance.
- Sub-accounts cannot create additional sub-accounts.
**Sub-account Characteristics**
- Virtual email addresses (may not require actual email verification).
- Independent trading accounts under master control.
- Cannot be deleted once created (only frozen).
- API keys must be generated separately for each sub-account.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
| Weight (IP) | Weight (UID) |
|---|---|
| 60 | 30 |
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Multi-Strategy Trading** — Separate accounts for different trading strategies.
- **Risk Segregation** — Isolate risky strategies from main account.
- **Team Management** — Individual accounts for team members.
- **Testing & Development** — Separate accounts for testing strategies.
- **Compliance & Reporting** — Separate accounts for regulatory reporting.
**Best Practices**
- Use descriptive email naming: `strategy1@domain.com`, `client_001@domain.com`.
- Track all created sub-accounts in your system.
- Implement access control for sub-account operations.
- Regular audit of sub-account activities.
'
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.
'
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'' \
--header ''X-COINS-APIKEY: <your api key>'' \
--data-urlencode ''accountName=test@coins.ph'' \
--data-urlencode ''timestamp=1499827319559'' \
--data-urlencode ''signature=<calculated_signature>''
'
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).
'
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).
| Code | Description |
|---|---|
| -4003 | Sub-account already exists. |
| -4004 | Maximum number of sub-accounts (30) reached. |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
/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
to master accounts only and provides comprehensive information about each sub-account including
creation time, email address, and freeze status. Supports pagination for efficient handling
of large numbers of sub-accounts.
**Access Control**
- This endpoint can only be accessed by master accounts.
- Sub-accounts cannot query other sub-accounts.
- Supports filtering by specific email address.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 10
**isFreeze Field**
- `false` = Active (can trade and transfer).
- `true` = Frozen (operations blocked).
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Account Inventory** — Get complete list of all sub-accounts.
- **Status Monitoring** — Check freeze status of all accounts.
- **Batch Operations** — Get list before performing bulk actions.
**Best Practices**
- Default limit is 10 accounts per page; maximum is 200.
- Cache results to reduce API calls (typical cache: 1–5 minutes).
'
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.
'
- 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'' \
--header ''X-COINS-APIKEY: <your api key>'' \
--data-urlencode ''page=1'' \
--data-urlencode ''limit=10'' \
--data-urlencode ''timestamp=1689744700710'' \
--data-urlencode ''signature=<calculated_signature>''
'
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).
'
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).
| Code | Description |
|---|---|
| -1022 | Signature for this request is not valid. |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
/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
allows master accounts to retrieve the asset holdings and balance details of their
sub-accounts, including free and locked balances for each asset.
**Access Control**
- This endpoint can only be accessed by master accounts.
- Master accounts have read-only access to sub-account balance information.
- Cannot be used by sub-accounts to query other sub-accounts.
**Balance Types**
- **Free Balance** — Available for trading, withdrawals, or transfers.
- **Locked Balance** — Reserved for open orders, pending withdrawals, or transfers.
- **Total Balance** = Free Balance + Locked Balance.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 10
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Portfolio Management** — Monitor total holdings across sub-accounts.
- **Risk Management** — Track locked vs free balances for liquidity planning.
- **Compliance** — Audit trail for sub-account asset holdings.
- **Rebalancing** — Identify sub-accounts needing asset redistribution.
**Best Practices**
- `email` parameter must be the exact email address of the target sub-account (case sensitive).
- All balance values are returned as strings to preserve precision.
- Use decimal libraries for financial calculations.
'
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'' \
--header ''X-COINS-APIKEY: <your api key>'' \
--data-urlencode ''email=testsub2@gmail.com'' \
--data-urlencode ''timestamp=1499827319559'' \
--data-urlencode ''signature=<calculated_signature>''
'
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).
| Code | Description |
|---|---|
| -1022 | Signature for this request is not valid. |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
/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
initiates an asset collection task that aggregates balances from all sub-accounts under the
master account. The collection process is asynchronous and tracked via a unique client request
ID. If there are tasks with a status of INIT, resubmission is not allowed to prevent
duplicate operations.
**How It Works**
1. Master account initiates collection with a unique `clientRequestId`.
2. System creates a collection task with status `INIT`.
3. System iterates through all sub-accounts and transfers available assets.
4. Task status updates to `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILED`.
5. Process is asynchronous — poll the status endpoint to track progress.
**Collection Scope**
- Collects from ALL sub-accounts; cannot select specific sub-accounts.
- Transfers ALL available (non-locked/frozen) assets.
- Skips sub-accounts with zero balance.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 1
**Status Values**
| Status | Description | Next Action |
|---|---|---|
| INIT | Task initiated, collection in progress | Wait and poll status |
| PROCESSING | Actively transferring assets | Wait and poll status |
| SUCCESS | All assets collected successfully | Complete |
| PARTIAL_SUCCESS | Some assets collected, some failed | Review failed sub-accounts |
| FAILED | Collection completely failed | Check error, retry if needed |
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Liquidity Management** — Pool assets for large trades.
- **Treasury Operations** — Aggregate funds for investment.
- **Risk Management** — Centralize assets for better control.
**Best Practices**
- Always use UUID format for `clientRequestId`.
- Store `clientRequestId` for later status checking; never reuse IDs.
- Poll the records endpoint every 10 seconds for INIT/PROCESSING tasks.
- Check if a collection task already exists before submitting.
'
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.
'
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'' \
--header ''X-COINS-APIKEY: <your api key>'' \
--data-urlencode ''clientRequestId=collect_001'' \
--data-urlencode ''remark=Monthly collection'' \
--data-urlencode ''timestamp=1499827319559'' \
--data-urlencode ''signature=<calculated_signature>''
'
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.
'
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).
| Code | Description |
|---|---|
| -10324 | Request repeated (duplicate clientRequestId with INIT status). |
| -1022 | Signature for this request is not valid. |
| -1102 | Mandatory parameter ''clientRequestId'' was not sent or is empty/null. |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
/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
the status and history of asset collection operations initiated via the
collect-from-sub-account endpoint. Supports filtering by specific clientRequestId or
paginated browsing of all collection records. Use this endpoint to monitor the progress
and outcome of asset collection tasks.
**Response Structure**
- Response is always an array, even for single record queries.
- Empty object `{}` if no matching records found.
- Each record contains `clientRequestId`, `status`, and `comment`.
**Status Values**
- `INIT` — Collection task has been initiated and is pending.
- `PROCESSING` — Collection is actively in progress.
- `SUCCESS` — All assets collected successfully from all sub-accounts.
- `PARTIAL_SUCCESS` — Some assets collected, some transfers failed.
- `FAILED` — Collection completely failed, no assets transferred.
---
## Additional Info
**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)
Weight: 1
**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)
- **Status Monitoring** — Query to check collection task progress.
- **Audit Trail** — Review history of all asset collection operations.
- **Reconciliation** — Verify completion of scheduled collections.
**Best Practices**
- Poll every 10 seconds for INIT/PROCESSING tasks; stop when status becomes final.
- Cache results for final states (SUCCESS, PARTIAL_SUCCESS, FAILED).
- Use specific `clientRequestId` queries for faster lookup.
'
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.
'
- 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
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 specific collection record
source: 'curl --get --location ''https://api.pro.coins.ph/openapi/v1/fund-collect/get-fund-record'' \
--header ''X-COINS-APIKEY: <your api key>'' \
--data-urlencode ''clientRequestId=collect-20240115-001'' \
--data-urlencode ''timestamp=1689744700710'' \
--data-urlencode ''signature=<calculated_signature>''
'
- lang: Shell
label: Query all collections (paginated)
source: 'curl --get --location ''https://api.pro.coins.ph/openapi/v1/fund-collect/get-fund-record'' \
--header ''X-COINS-APIKEY: <your api key>'' \
--data-urlencode ''page=1'' \
--data-urlencode ''size=50'' \
--data-urlencode ''timestamp=1689744700710'' \
--data-urlencode ''signature=<calculated_signature>''
'
responses:
'200':
description: Asset collection records returned 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: 'Collection task status. Values: INIT, PROCESSING, SUCCESS, PARTIAL_SUCCESS, FAILED.
'
example: SUCCESS
comment:
type: string
description: Additional information or error details.
example: ''
examples:
success:
summary: Record (SUCCESS)
value:
clientRequestId: collect-20240115-001
status: SUCCESS
comment: ''
init:
summary: Record (INIT)
value:
clientRequestId: collect-20240115-001
status: INIT
comment: ''
partial:
summary: Record (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).
| Code | Description |
|---|---|
| -1022 | Signature for this request is not valid. |
For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).
'
/openapi/v1/sub-account/apikey/ip-restriction:
get:
tags:
- Sub Account
summary: Get IP Restriction for a Sub-account API Key (For Master Account)
description: 'Query detailed IP restriction settings for a sub-account API key. This endpoint allows the
master account to check whether IP restrictions are enabled for a specific sub-account''s API
key and retrieve associated metadata. Use this endpoint to verify security configurations
and ensure proper access control is in place for sub-accounts.
**Access Control**
- This endpoint can only be accessed by master accounts.
- Requires both master account API key (in header) and sub-account API key (in query parameter).
- Cannot be called by sub-accounts.
**Role/Permission Codes**
The `role` field is a comma-separated string of permission codes:
| Code | Permission | Description |
|---|---|---|
| 0 | READ_ONLY | Query data only, no modifications |
| 2 | TRADE_ONLY | Place and cancel orders |
| 3 | CONVERT_ONLY | Execute currency conversions |
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coinsph/refs/heads/main/openapi/coinsph-sub-account-api-openapi.yml