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: '' \ --data-urlencode ''accountName=test@coins.ph'' \ --data-urlencode ''timestamp=1499827319559'' \ --data-urlencode ''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: '' \ --data-urlencode ''page=1'' \ --data-urlencode ''limit=10'' \ --data-urlencode ''timestamp=1689744700710'' \ --data-urlencode ''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: '' \ --data-urlencode ''email=testsub2@gmail.com'' \ --data-urlencode ''timestamp=1499827319559'' \ --data-urlencode ''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: '' \ --data-urlencode ''clientRequestId=collect_001'' \ --data-urlencode ''remark=Monthly collection'' \ --data-urlencode ''timestamp=1499827319559'' \ --data-urlencode ''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: '' \ --data-urlencode ''clientRequestId=collect-20240115-001'' \ --data-urlencode ''timestamp=1689744700710'' \ --data-urlencode ''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: '' \ --data-urlencode ''page=1'' \ --data-urlencode ''size=50'' \ --data-urlencode ''timestamp=1689744700710'' \ --data-urlencode ''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 | | 4 | CRYPTO_WALLET | Manage crypto wallet operations | | 5 | FIAT_ONLY | Fiat currency operations (Cash-In/Out) | | 6 | ACCOUNT_ONLY | Account management, sub-account, transfers | --- ## 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) - **Security Audit** — Verify IP restriction settings for all sub-accounts. - **Compliance Check** — Ensure production accounts have IP restrictions enabled. - **Onboarding Verification** — Confirm new sub-account security configuration. **Best Practices** - Always verify `ipRestrict` is `true` for production environments. - Check role assignments match intended use. - Use correct sub-account API key (not master) in the `apikey` query parameter. ' operationId: get_sub_account_ip_restriction parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: Master account API key for authentication. - in: query name: apikey required: true schema: type: string example: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A description: The sub-account's API key (not the master account's API key). - in: query name: email required: true schema: type: string example: subaccount@example.com description: Email address of the sub-account whose API key IP restriction is being queried. - 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: Get IP restriction settings source: 'curl --get --location ''https://api.pro.coins.ph/openapi/v1/sub-account/apikey/ip-restriction'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''apikey='' \ --data-urlencode ''email=testaccount@example.com'' \ --data-urlencode ''recvWindow=60000'' \ --data-urlencode ''timestamp=1689744700710'' \ --data-urlencode ''signature='' ' responses: '200': description: IP restriction settings returned successfully. content: application/json: schema: type: object properties: ipRestrict: type: boolean description: 'true = IP whitelist is enabled; false = IP restriction is disabled. ' example: true role: type: string description: 'Comma-separated permission codes. 0=READ_ONLY, 2=TRADE_ONLY, 3=CONVERT_ONLY, 4=CRYPTO_WALLET, 5=FIAT_ONLY, 6=ACCOUNT_ONLY. ' example: 2,3,4,5,6 updateTime: type: integer format: int64 description: Unix timestamp (ms) when settings were last updated. example: 1689744700710 examples: restricted: summary: IP Restriction Enabled value: ipRestrict: true role: 2,3,4,5,6 updateTime: 1689744700710 unrestricted: summary: IP Restriction Disabled value: ipRestrict: false role: '0' updateTime: 1689744700710 default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | -4003 | Invalid sub-account email. | | -2015 | Invalid API-key, IP, or permissions for action. | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/apikey/add-ip-restriction: post: tags: - Sub Account summary: Add IP Restriction for Sub-Account API Key (For Master Account) description: "Add or update IP whitelist restrictions for a sub-account's API key. This endpoint enables\nthe master account to configure which IP addresses are allowed to use a specific sub-account\nAPI key, enhancing security by limiting access to trusted locations only. Multiple IP addresses\ncan be added in a single request, and the IP restriction status can be toggled between\nrestricted and unrestricted modes.\n\n**Access Control**\n\n- This endpoint can only be accessed by master accounts.\n- Requires both master account API key (in header) and sub-account API key (in request body).\n- Changes take effect immediately.\n\n**ipRestriction Modes**\n\n- **\"1\" — Restricted Mode (Recommended for Production)**: Only whitelisted IP addresses can\n use the API key. If no `ipAddress` provided, the API key becomes unusable.\n- **\"2\" — Unrestricted Mode (Use with Caution)**: API key can be used from any IP address.\n Not recommended for production. `ipAddress` parameter is ignored in this mode.\n\n---\n\n## Additional Info\n\n**Rate Limit** [\U0001F4D6 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 30\n\n**Use Cases** [\U0001F9E9 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Initial Security Setup** — Configure IP restrictions during sub-account onboarding.\n- **IP Whitelist Update** — Add new trusted IP addresses as business needs change.\n- **Multi-location Support** — Whitelist IPs from multiple office locations.\n- **VPN Integration** — Configure VPN gateway IP for remote access.\n\n**Best Practices**\n\n- Use static IP addresses only (not dynamic IPs).\n- Limit to necessary IPs only (principle of least privilege).\n- Document each IP address purpose.\n- Test thoroughly before production deployment.\n" operationId: add_sub_account_ip_restriction parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: Master account API key for authentication. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - apikey - email - ipRestriction - timestamp - signature properties: apikey: type: string example: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A description: The sub-account's API key to configure. email: type: string example: subaccount@example.com description: Email address of the sub-account whose API key is being configured. ipAddress: type: string example: 8.8.8.8,1.1.1.1 description: 'IP addresses to whitelist, separated by commas (IPv4 format). Required when ipRestriction=1; otherwise the API key becomes unusable. ' ipRestriction: type: string enum: - '1' - '2' example: '1' description: 'IP Restriction status. "1" = Restrict to trusted IPs only. "2" = Unrestricted (any IP). ' 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: Add IP restriction (multiple IPs) source: 'curl --location --request POST ''https://api.pro.coins.ph/openapi/v1/sub-account/apikey/add-ip-restriction'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''apikey='' \ --data-urlencode ''email=subaccount@example.com'' \ --data-urlencode ''ipAddress=8.8.8.8,1.1.1.1'' \ --data-urlencode ''ipRestriction=1'' \ --data-urlencode ''timestamp=1689744700710'' \ --data-urlencode ''signature='' ' responses: '200': description: IP restriction updated successfully. content: application/json: schema: type: object properties: apikey: type: string description: The sub-account API key that was configured. ipList: type: array items: type: string description: Current list of whitelisted IP addresses. example: - 8.8.8.8 - 1.1.1.1 ipRestrict: type: boolean description: Whether IP restriction is enabled. example: true role: type: string description: Comma-separated permission codes. example: 2,3,4,5,6 updateTime: type: integer format: int64 description: Unix timestamp (ms) when settings were last updated. example: 1689744700710 examples: success: summary: IP Restriction Enabled with Multiple IPs value: apikey: ipList: - 8.8.8.8 - 1.1.1.1 ipRestrict: true role: 2,3,4,5,6 updateTime: 1689744700710 default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | -4003 | Invalid sub-account email. | | -2015 | Invalid API-key, IP, or permissions for action. | | -1102 | Invalid IP address format. | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/apikey/delete-ip-restriction: post: tags: - Sub Account summary: Delete IP List For a Sub-account API Key (For Master Account) description: 'Delete specific IP addresses from a sub-account API key''s whitelist. This endpoint allows the master account to remove one or more IP addresses from the whitelist without disabling IP restrictions entirely. The API key will remain restricted to the remaining whitelisted IPs after the deletion. Multiple IP addresses can be removed in a single request by providing them in a comma-separated format. **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 request body). - Changes take effect immediately — removed IPs lose access instantly. > ⚠️ **Critical Warning**: If you delete ALL whitelisted IPs, the API key becomes UNUSABLE. > An empty `ipList` with `ipRestrict=true` means NO IP can use the key. > Always ensure at least one IP remains unless intentionally disabling the key. --- ## Additional Info **Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction) Weight: 30 **Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk) - **Security Incident Response** — Immediately revoke access from compromised IP. - **Access Management** — Remove IP when employee leaves or role changes. - **Temporary Access Cleanup** — Remove temporary IPs added for troubleshooting. - **Regular Maintenance** — Clean up unused or outdated IPs from whitelist. **Best Practices** - Always maintain at least one working IP unless intentional deactivation. - Verify with team members before removing their IPs. - Confirm IPs are actually in the whitelist before attempting deletion. ' operationId: delete_sub_account_ip_restriction parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: Master account API key for authentication. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - apikey - email - ipAddress - timestamp - signature properties: apikey: type: string example: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A description: The sub-account's API key to modify. email: type: string example: subaccount@example.com description: Email address of the sub-account whose API key IP whitelist is being modified. ipAddress: type: string example: 8.8.8.8,1.1.1.1 description: 'IP addresses to remove from the whitelist, separated by commas (IPv4 format). These IPs will no longer be able to use the API key after deletion. ' 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: Delete IP addresses from whitelist source: 'curl --location --request POST ''https://api.pro.coins.ph/openapi/v1/sub-account/apikey/delete-ip-restriction'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''apikey='' \ --data-urlencode ''email=subaccount@example.com'' \ --data-urlencode ''ipAddress=8.8.8.8,1.1.1.1'' \ --data-urlencode ''timestamp='' \ --data-urlencode ''signature='' ' responses: '200': description: IP addresses removed from whitelist successfully. content: application/json: schema: type: object properties: ipList: type: array items: type: string description: Remaining whitelisted IP addresses after deletion. example: - 192.168.1.100 ipRestrict: type: boolean description: Whether IP restriction is still enabled. example: true role: type: string description: Comma-separated permission codes. example: 2,3,4,5,6 updateTime: type: integer format: int64 description: Unix timestamp (ms) when settings were last updated. example: 1689744700710 examples: some_remaining: summary: Some IPs Remaining After Deletion value: ipList: - 192.168.1.100 - 203.0.113.10 ipRestrict: true role: 2,3,4,5,6 updateTime: 1689744700710 all_removed: summary: All IPs Removed (API Key Now Unusable) value: ipList: [] ipRestrict: true role: 2,3,4,5,6 updateTime: 1689744700710 default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | -4003 | Invalid sub-account email. | | -2015 | Invalid API-key, IP, or permissions for action. | | -1104 | IP address not found in whitelist. | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/transfer/sub-history: get: tags: - Sub Account summary: Sub-account Transfer History (USER_DATA) description: 'Retrieve the transfer history for a specific sub-account. This endpoint must be called using the **sub-account''s API key**. **Key Notes** - Only accessible by sub-accounts (not the master account). - If `type` is not sent, records of type 2 (transfer out) will be returned by default. - If `startTime` and `endTime` are not sent, the recent 30-day data will be returned. - Default and maximum `limit` is 500 records. **Transfer Type Values** | type | Description | |---|---| | 1 | Transfer In (incoming to sub-account) | | 2 | Transfer Out (outgoing from sub-account) | --- ## 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) - **Sub-Account Transfer History** — View all incoming or outgoing transfers for the calling sub-account. - **Audit Trail** — Verify all fund movements for compliance and internal record-keeping. - **Reconciliation** — Match transfers to balance changes. **Best Practices** - Use `type=1` for incoming transfers; `type=2` for outgoing transfers. - Filter by `asset` to scope results to a specific cryptocurrency. - Use `startTime` and `endTime` for time-range queries. - Default behavior returns type 2 (transfer out) if type is not specified. ' operationId: get_sub_account_transfer_history parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: Sub-account API key for authentication. - in: query name: asset required: false schema: type: string example: ETH description: Filter by asset symbol. - in: query name: type required: false schema: type: integer example: 1 description: 'Transfer direction: 1=Transfer In, 2=Transfer Out. Defaults to 2 if not provided.' - in: query name: startTime required: false schema: type: integer format: int64 example: 1638253478000 description: Start time in milliseconds. - in: query name: endTime required: false schema: type: integer format: int64 example: 1640931878000 description: End time in milliseconds (exclusive). - in: query name: limit required: false schema: type: integer example: 50 description: 'Number of records to return. Default and maximum: 500.' - in: query name: clientTranId required: false schema: type: string example: TRANSFER_20231201_001 description: Client transaction ID for filtering. - in: query name: recvWindow required: false schema: type: integer format: int64 minimum: 0 maximum: 60000 example: 5000 description: 'Request validity window in milliseconds. Default: 5000, Maximum: 60000.' - in: query name: timestamp required: true schema: type: integer format: int64 minimum: 0 example: 1638253478000 description: Unix timestamp in milliseconds. - in: query name: signature required: true schema: type: string description: HMAC SHA256 signature of the query string [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order) x-codeSamples: - lang: Shell label: Sub-account Transfer History source: 'curl --get --location ''https://api.pro.coins.ph/openapi/v1/sub-account/transfer/sub-history'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''asset=ETH'' \ --data-urlencode ''type=1'' \ --data-urlencode ''startTime=1638253478000'' \ --data-urlencode ''endTime=1640931878000'' \ --data-urlencode ''limit=100'' \ --data-urlencode ''timestamp=1640931878000'' \ --data-urlencode ''signature='' ' responses: '200': description: Sub-account transfer history records. content: application/json: schema: type: object properties: result: type: array items: type: object properties: clientTranId: type: string description: Client transaction ID. example: '1' fromEmail: type: string description: Source account email. example: test@coins.ph toEmail: type: string description: Destination account email. example: test1@coins.ph asset: type: string description: Asset symbol. example: BTC amount: type: string description: Transfer amount. example: '0.1' type: type: integer description: 'Transfer direction: 1=Transfer In, 2=Transfer Out.' example: 2 createTime: type: integer format: int64 description: Creation timestamp in milliseconds. example: 1638253478000 status: type: string description: Transfer status. example: SUCCESS total: type: integer description: Total count of records. example: 1 examples: success: summary: Sub-account transfer history value: result: - clientTranId: TRANSFER_20231201_002 fromEmail: master@coins.ph toEmail: sub1@coins.ph asset: ETH amount: '1.5' type: 1 createTime: 1638253578000 status: SUCCESS total: 2 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 | | -1102 | This endpoint applies to sub-accounts only | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/transfer/sub-to-master: post: tags: - Sub Account summary: Transfer to Master (USER_DATA) description: 'Sub-account can initiate a transfer from itself to the master account. This endpoint must be called using the **sub-account''s API key**, not the master account''s API key. **Key Notes** - Called by the sub-account itself, not the master account. - Transfer destination is always the master account (no need to specify `toEmail`). - Transfer source is always the calling sub-account (no need to specify `fromEmail`). - `clientTranId` can be used as an idempotency key. --- ## Additional Info **Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction) Weight: 100 **Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk) - **Sub-Account Fund Return** — Sub-account sends assets back to master without requiring master account intervention. - **Balance Consolidation** — Periodically sweep sub-account balances into the master account. **Best Practices** - Must use sub-account''s API key for authentication (not master account API key). - Use `clientTranId` for idempotency to safely retry on network failures. - Check sub-account balance before transfer to avoid insufficient balance errors. ' operationId: post_sub_account_transfer_to_master parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: Sub-account API key for authentication. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - asset - amount - timestamp - signature properties: asset: type: string example: BTC description: Asset symbol to transfer (e.g., BTC, ETH, PHP). amount: type: string example: '0.01' description: Amount to transfer to master account. Must be greater than 0. clientTranId: type: string maxLength: 100 example: SUB_TRANSFER_20231201_001 description: Client transaction ID for idempotency. Must be unique. 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: 1638253478000 description: Unix timestamp in milliseconds. signature: type: string description: HMAC SHA256 signature of the query string [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order) x-codeSamples: - lang: Shell label: Transfer to Master source: 'curl --location --request POST ''https://api.pro.coins.ph/openapi/v1/sub-account/transfer/sub-to-master'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''asset=BTC'' \ --data-urlencode ''amount=0.01'' \ --data-urlencode ''clientTranId=SUB_TRANSFER_20231201_001'' \ --data-urlencode ''timestamp=1638253478000'' \ --data-urlencode ''signature='' ' responses: '200': description: Transfer to master submitted successfully. content: application/json: schema: type: object properties: result: type: boolean description: true = success, false = failed. example: true examples: success: summary: Transfer to master succeeded value: result: true 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 | | -1003 | Insufficient balance or duplicate clientTranId | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/transfer/universal-transfer: post: tags: - Sub Account summary: Universal Transfer (USER_DATA) description: 'Master account can initiate a transfer from any of its sub-accounts to the master account, or from the master account to any sub-account, or between sub-accounts. **Key Notes** - Only accessible by master accounts. - Transfer from master account by default if `fromEmail` is not sent. - Transfer to master account by default if `toEmail` is not sent. - Specify at least one of `fromEmail` and `toEmail`. - `clientTranId` can be used as an idempotency key. **Supported transfer scenarios:** - Master account → sub-account - Sub-account → master account - Sub-account → sub-account --- ## Additional Info **Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction) Weight: 100 **Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk) - **Cross-Account Asset Management** — Move assets between master and sub-account wallets. - **Consolidation** — Aggregate sub-account funds into the master account. - **Fund Distribution** — Distribute funds from the master account to sub-accounts. **Best Practices** - Use `clientTranId` for idempotency to safely retry without risk of duplication. - Verify source account has sufficient balance before initiating transfer. - Use string format for amounts to preserve decimal precision. ' operationId: post_sub_account_universal_transfer parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: API key for authentication. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - asset - amount - timestamp - signature properties: fromEmail: type: string example: sub@coins.ph description: Source account email. Defaults to master account if not provided. toEmail: type: string example: sub@coins.ph description: Destination account email. Defaults to master account if not provided. clientTranId: type: string maxLength: 100 example: TRANSFER_20231201_001 description: Client transaction ID for idempotency. Must be unique. asset: type: string example: PHP description: Asset symbol to transfer (e.g., BTC, ETH, PHP). amount: type: string example: '1000' description: Amount to transfer. Must be greater than 0. 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: 1638253478000 description: Unix timestamp in milliseconds. signature: type: string description: HMAC SHA256 signature of the query string [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order) x-codeSamples: - lang: Shell label: Master to Sub-account Transfer source: 'curl --location --request POST ''https://api.pro.coins.ph/openapi/v1/sub-account/transfer/universal-transfer'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''toEmail=sub@coins.ph'' \ --data-urlencode ''asset=PHP'' \ --data-urlencode ''amount=1000'' \ --data-urlencode ''timestamp=1638253478000'' \ --data-urlencode ''clientTranId=TRANSFER_20231201_001'' \ --data-urlencode ''signature='' ' - lang: Shell label: Sub-account to Master Transfer source: 'curl --location --request POST ''https://api.pro.coins.ph/openapi/v1/sub-account/transfer/universal-transfer'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''fromEmail=sub@coins.ph'' \ --data-urlencode ''asset=PHP'' \ --data-urlencode ''amount=1000'' \ --data-urlencode ''timestamp=1638253478000'' \ --data-urlencode ''clientTranId=TRANSFER_20231201_001'' \ --data-urlencode ''signature='' ' responses: '200': description: Universal transfer submitted successfully. content: application/json: schema: type: object properties: clientTransferId: type: string description: Client-provided transfer ID. example: '14875736398419995271' result: type: boolean description: true = success, false = failed. example: true examples: success: summary: Universal transfer submitted value: clientTransferId: '14875736398419995271' result: true 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 | | -1003 | Insufficient balance or duplicate clientTranId | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/transfer/universal-transfer-history: get: tags: - Sub Account summary: Query Universal Transfer History (USER_DATA) description: 'Retrieve the universal transfer history for the master account. Only accessible by master accounts. **Key Notes** - `fromEmail` and `toEmail` cannot be sent at the same time. - Returns `fromEmail` equal to master account email by default. - The query time period must be less than 30 days. - If `startTime` and `endTime` are not sent, returns records of the last 30 days by default. - Default and maximum `limit` is 500 records. --- ## 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) - **Transfer Audit** — Review all universal transfers between master and sub-accounts. - **Status Tracking** — Look up a specific transfer by `clientTranId`. - **Reconciliation** — Match universal transfers against balance changes. **Best Practices** - Use `fromEmail` to see all outgoing transfers from a specific account. - Use `toEmail` to see all incoming transfers to a specific account. Cannot use both simultaneously. - Maximum query period is 30 days; use `startTime` and `endTime` for specific periods. ' operationId: get_sub_account_universal_transfer_history parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: Master account API key for authentication. - in: query name: fromEmail required: false schema: type: string example: master@coins.ph description: Source account email. Cannot be used with toEmail. Returns master account email by default. - in: query name: toEmail required: false schema: type: string example: sub1@coins.ph description: Destination account email. Cannot be used with fromEmail. - in: query name: clientTranId required: false schema: type: string example: TRANSFER_20231201_001 description: Client transaction ID for filtering. - in: query name: tokenId required: false schema: type: string example: token_12345 description: Token/transaction ID for filtering. - in: query name: startTime required: false schema: type: integer format: int64 example: 1638253478000 description: Start time in milliseconds. - in: query name: endTime required: false schema: type: integer format: int64 example: 1640931878000 description: End time in milliseconds (exclusive). - in: query name: limit required: false schema: type: integer example: 50 description: 'Number of records to return. Default and maximum: 500.' - in: query name: recvWindow required: false schema: type: integer format: int64 minimum: 0 maximum: 60000 example: 5000 description: 'Request validity window in milliseconds. Default: 5000, Maximum: 60000.' - in: query name: timestamp required: true schema: type: integer format: int64 minimum: 0 example: 1638253478000 description: Unix timestamp in milliseconds. - in: query name: signature required: true schema: type: string description: HMAC SHA256 signature of the query string [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order) x-codeSamples: - lang: Shell label: Query Universal Transfer History source: 'curl --get --location ''https://api.pro.coins.ph/openapi/v1/sub-account/transfer/universal-transfer-history'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''timestamp=1638253478000'' \ --data-urlencode ''signature='' ' responses: '200': description: Universal transfer history records. content: application/json: schema: type: object properties: result: type: array items: type: object properties: clientTranId: type: string description: Client transaction ID. example: '1' fromEmail: type: string description: Source account email. example: test@coins.ph toEmail: type: string description: Destination account email. example: test1@coins.ph asset: type: string description: Asset symbol. example: BTC amount: type: string description: Transfer amount. example: '0.1' createTime: type: integer format: int64 description: Creation timestamp in milliseconds. example: 1638253478000 status: type: string description: Transfer status. example: SUCCESS total: type: integer description: Total count of records. example: 1 examples: success: summary: Universal transfer history value: result: - clientTranId: '1' fromEmail: test@coins.ph toEmail: test1@coins.ph asset: BTC amount: '0.1' createTime: 1638253478000 status: SUCCESS total: 1 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 | | -1003 | Query time period exceeds 30 days | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/wallet/deposit/address: get: tags: - Sub Account summary: Get Sub Account Deposit Address (USER_DATA) description: 'Fetch the deposit address for a specific coin and network belonging to a sub-account. Only accessible by master accounts. **Key Notes** - Both `email` (sub-account), `coin`, and `network` are required. - For coins requiring a memo or tag (e.g., XRP, XLM), the `addressTag` field in the response must be included with the deposit. --- ## 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) - **Sub-Account Deposit Routing** — Generate deposit addresses for sub-accounts so they can receive funds independently. - **Multi-Network Support** — Fetch ERC-20 vs BEP-20 addresses for the same coin by specifying the `network` parameter. **Best Practices** - Always specify `network` for multi-chain coins to avoid depositing on the wrong chain. - Include the `addressTag` in the deposit instructions for memo-based coins (e.g., XRP, XLM) to prevent loss of funds. - Cache the address per sub-account + coin + network combination since deposit addresses rarely change. ' operationId: get_sub_account_deposit_address parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: API key for authentication. - in: query name: email required: true schema: type: string example: subaccount@example.com description: Sub-account email address. - in: query name: coin required: true schema: type: string example: ETH description: Coin symbol (from All Coins' Information API). - in: query name: network required: true schema: type: string example: ETH description: Network identifier (from All Coins' Information API). - in: query name: recvWindow required: false schema: type: integer format: int64 minimum: 0 maximum: 60000 example: 5000 description: 'Request validity window in milliseconds. Default: 5000, Maximum: 60000.' - in: query name: timestamp required: true schema: type: integer format: int64 minimum: 0 example: 1638253478000 description: Unix timestamp in milliseconds. - in: query name: signature required: true schema: type: string description: HMAC SHA256 signature of the query string [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order) x-codeSamples: - lang: Shell label: Get Sub Account Deposit Address source: 'curl --get --location ''https://api.pro.coins.ph/openapi/v1/sub-account/wallet/deposit/address'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''email=subaccount@example.com'' \ --data-urlencode ''coin=ETH'' \ --data-urlencode ''network=ETH'' \ --data-urlencode ''timestamp=1638253478000'' \ --data-urlencode ''signature='' ' responses: '200': description: Sub-account deposit address details. content: application/json: schema: type: object properties: coin: type: string description: Coin symbol. example: ETH address: type: string description: Deposit address. example: '0xfe98628173830bf79c59f04585ce41f7de168784' addressTag: type: string description: Address tag or memo (for memo-based coins such as XRP, XLM). example: '' examples: success: summary: ETH sub-account deposit address value: coin: ETH address: '0xfe98628173830bf79c59f04585ce41f7de168784' addressTag: '' xrp_example: summary: XRP sub-account deposit address (with tag) value: coin: XRP address: rN7n7otQDd6FczFgLdlqtyMVrn3HMvoxzp addressTag: '12345678' 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 | | -1102 | Mandatory parameter was not sent, was empty/null, or malformed | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/v1/sub-account/wallet/deposit/history: get: tags: - Sub Account summary: Get Sub Account Deposit History (USER_DATA) description: 'Fetch deposit history for a sub-account. Only accessible by master accounts. **Key Notes** - `email` (sub-account) is required. - Use `offset` for pagination through large deposit histories. - Default and maximum limit is 1000 records. **Deposit Status Codes** | Status | Description | |---|---| | 0 | Processing | | 1 | Success | | 2 | Failed | | 3 | Need Fill Data (travel rule info required) | --- ## 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) - **Sub-Account Deposit Monitoring** — Track all deposits into a sub-account for balance reconciliation. - **Reconciliation** — Match sub-account deposits to balance changes to ensure funds are correctly credited. - **Deposit Confirmation** — Confirm that a specific deposit has arrived and been processed. **Best Practices** - Filter by `coin` and time range (`startTime`/`endTime`) to reduce response size. - Use `offset` for pagination when a sub-account has a large deposit history. ' operationId: get_sub_account_deposit_history parameters: - in: header name: X-COINS-APIKEY required: true schema: type: string description: API key for authentication. - in: query name: email required: true schema: type: string example: subaccount@example.com description: Sub-account email address. - in: query name: coin required: false schema: type: string example: BNB description: Filter by coin symbol. - in: query name: txId required: false schema: type: string example: 0x123abc... description: Filter by blockchain transaction ID. - in: query name: depositId required: false schema: type: string example: d_76980051936688537e description: Filter by deposit ID. - in: query name: status required: false schema: type: integer example: 1 description: 'Filter by deposit status: 0=Processing, 1=Success, 2=Failed, 3=Need Fill Data.' - in: query name: startTime required: false schema: type: integer format: int64 example: 1638253478000 description: 'Start time in milliseconds. Default: 90 days from current timestamp.' - in: query name: endTime required: false schema: type: integer format: int64 example: 1640845478000 description: End time in milliseconds. Maximum range is 90 days. - in: query name: offset required: false schema: type: integer example: 0 description: 'Pagination offset. Default: 0.' - in: query name: limit required: false schema: type: integer example: 100 description: 'Number of records to return. Default and maximum: 1000.' - in: query name: recvWindow required: false schema: type: integer format: int64 minimum: 0 maximum: 60000 example: 5000 description: 'Request validity window in milliseconds. Default: 5000, Maximum: 60000.' - in: query name: timestamp required: true schema: type: integer format: int64 minimum: 0 example: 1638253478000 description: Unix timestamp in milliseconds. - in: query name: signature required: true schema: type: string description: HMAC SHA256 signature of the query string [📖 Learn More](https://api.docs.coins.ph/reference/general#signed-endpoint-examples-for-post-openapiv1order) x-codeSamples: - lang: Shell label: Get Sub Account Deposit History source: 'curl --location --get ''https://api.pro.coins.ph/openapi/v1/sub-account/wallet/deposit/history'' \ --header ''X-COINS-APIKEY: '' \ --data-urlencode ''email=subaccount@example.com'' \ --data-urlencode ''timestamp=1638253478000'' \ --data-urlencode ''signature='' ' responses: '200': description: Sub-account deposit history records. content: application/json: schema: type: array items: type: object properties: id: type: string description: Deposit record ID. example: d_76980051936688537e amount: type: string description: Deposited amount. example: '0.001' coin: type: string description: Coin symbol. example: BNB network: type: string description: Network identifier. example: BNB status: type: integer description: 'Deposit status: 0=Processing, 1=Success, 2=Failed, 3=Need Fill Data.' example: 0 address: type: string description: Deposit address. example: bnb1ns6ltw4s5hg4n85vdthaad7hq5m4gtkgf23 addressTag: type: string description: Address tag or memo. example: '101764890' txId: type: string description: Blockchain transaction ID. example: 98A3EA5606CB3336D34886C83F0F95ECE4F1F5919E9BD0066E5BF3BF264FACE42EB insertTime: type: integer format: int64 description: Timestamp of deposit creation in milliseconds. example: 1661493146000 confirmNo: type: integer description: Number of blockchain confirmations. example: 10 examples: success: summary: Sub-account deposit history value: - id: d_76980051936688537e amount: '0.001' coin: BNB network: BNB status: 0 address: bnb1ns6ltw4s5hg4n85vdthaad7hq5m4gtkgf23 addressTag: '101764890' txId: 98A3EA5606CB3336D34886C83F0F95ECE4F1F5919E9BD0066E5BF3BF264FACE42EB insertTime: 1661493146000 confirmNo: 10 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 | | -1102 | Mandatory parameter was not sent, was empty/null, or malformed | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-COINS-APIKEY x-readme: proxy-enabled: false