openapi: 3.0.0 info: title: TRADING Account Convert 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: Convert description: Convert quote and acceptance operations. paths: /openapi/convert/v1/get-supported-trading-pairs: post: tags: - Convert summary: Get Supported Trading Pairs (TRADE) description: 'Returns all supported trading pairs available for the Convert feature. Each pair includes the source and target currency, amount limits, and decimal precision. --- ## 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) - **Pre-conversion Validation** — Check if a desired currency pair is supported before requesting a quote - **Limit Discovery** — Retrieve min/max source amounts to validate input before submitting **Best Practices** - Cache the response and refresh periodically; supported pairs change infrequently - Use the `precision` field to format display amounts correctly for each pair - Filter by `sourceCurrency` or `targetCurrency` client-side to reduce UI clutter ' operationId: convert_get_supported_trading_pairs 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: - timestamp - signature properties: type: type: string enum: - CONVERT - LIGHTNING - LIGHTNING_WITHDRAW - OTC description: "Conversion type filter. If omitted, returns all supported trading pairs. Accepted values:\n\n- `CONVERT` — Standard Convert mode\n- `LIGHTNING` — Lightning Convert mode\n- `LIGHTNING_WITHDRAW` — Lightning Withdraw mode\n- `OTC` — OTC-Convert mode (whitelist-only feature, minimum trade size $20,000;\n contact otcdesk_ph@coins.ph to request access)\n" 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 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: Get Supported Trading Pairs source: 'curl --location ''https://api.pro.coins.ph/openapi/convert/v1/get-supported-trading-pairs'' \ --header ''X-COINS-APIKEY: your_api_key'' \ --data-urlencode ''timestamp=1700000000000'' \ --data-urlencode ''signature=your_signature'' ' responses: '200': description: List of supported trading pairs. content: application/json: schema: type: array items: type: object properties: sourceCurrency: type: string description: The source currency of the trading pair. example: PHP targetCurrency: type: string description: The target currency of the trading pair. example: BTC minSourceAmount: type: string description: Minimum source amount allowed for conversion. example: '1000' maxSourceAmount: type: string description: Maximum source amount allowed for conversion. example: '15000' precision: type: string description: Decimal precision for the conversion amount. example: '2' examples: success: summary: PHP/BTC trading pair value: - sourceCurrency: PHP targetCurrency: BTC minSourceAmount: '1000' maxSourceAmount: '15000' precision: '2' default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | -1100 | Illegal characters found in parameter | | -1104 | Not all sent parameters were read | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/convert/v1/get-quote: post: tags: - Convert summary: Fetch a Quote (TRADE) description: 'Fetch a real-time conversion quote for a given currency pair and amount. Provide either `sourceAmount` or `targetAmount`, but not both. The quote is valid for the number of seconds specified in the `expiry` field of the response. **Key Notes** - The quote `quoteId` must be used with the Accept Quote endpoint before expiry. --- ## 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) - **Large Volume Conversion (OTC Mode)** — Enable high-value conversions through our OTC desk, offering dedicated liquidity and execution for trades above **$20,000**. Access is available to whitelisted users only. **Best Practices** - Fetch a new quote immediately before accepting; quotes expire quickly (see `expiry` field) - Use `sourceAmount` for fixed-spend conversions; use `targetAmount` for fixed-receive conversions - Leave the `type` parameter empty or omit it entirely to perform a standard Convert transaction. Set `type` to `OTC` to execute the conversion through OTC Mode (whitelisted users only). ' operationId: convert_get_quote 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: - sourceCurrency - targetCurrency - timestamp - signature properties: sourceCurrency: type: string description: The source currency for the conversion. example: PHP targetCurrency: type: string description: The target currency for the conversion. example: BTC sourceAmount: type: string description: Amount of source currency to convert. Provide this OR targetAmount, not both. example: '5000' targetAmount: type: string description: Amount of target currency to receive. Provide this OR sourceAmount, not both. type: type: string enum: - CONVERT - LIGHTNING - LIGHTNING_WITHDRAW - OTC example: CONVERT description: "Conversion type.\n\n- `CONVERT` — Standard Convert mode (default)\n- `LIGHTNING` — Lightning Convert mode\n- `LIGHTNING_WITHDRAW` — Lightning Withdraw mode\n- `OTC` — OTC-Convert mode (whitelist-only feature, minimum trade size $20,000;\n contact otcdesk_ph@coins.ph to request access)\n" 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 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: Fetch a Quote source: 'curl --location ''https://api.pro.coins.ph/openapi/convert/v1/get-quote'' \ --header ''X-COINS-APIKEY: your_api_key'' \ --data-urlencode ''sourceCurrency=PHP'' \ --data-urlencode ''targetCurrency=BTC'' \ --data-urlencode ''sourceAmount=5000'' \ --data-urlencode ''timestamp=1700000000000'' \ --data-urlencode ''signature=your_signature'' ' responses: '200': description: Conversion quote details. content: application/json: schema: type: object properties: quoteId: type: string description: Unique identifier for this quote. example: q_abc123 sourceCurrency: type: string description: Source currency. example: PHP targetCurrency: type: string description: Target currency. example: BTC sourceAmount: type: string description: Source amount for this quote. example: '5000' price: type: string description: Exchange rate (source per target). example: '3500000' targetAmount: type: string description: Target amount to receive. example: '0.00142857' expiry: type: integer description: Number of seconds until this quote expires. example: 30 examples: success: summary: PHP to BTC quote value: quoteId: q_abc123 sourceCurrency: PHP targetCurrency: BTC sourceAmount: '5000' price: '3500000' targetAmount: '0.00142857' expiry: 30 default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | -1100 | Illegal characters found in parameter | | -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/convert/v1/accept-quote: post: tags: - Convert summary: Accept the Quote (TRADE) description: 'Accept a previously fetched conversion quote using its `quoteId`. The conversion is executed immediately upon acceptance. **Key Notes** - The `type` parameter, if provided, must match the type used in the Get Quote request. - Quotes expire after the number of seconds indicated by the `expiry` field in the quote response. --- ## 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) - **Instant Conversion** — Execute a currency swap immediately at the quoted rate - **Two-Step Convert Flow** — Combine with Get Quote to build a confirm-then-execute UX - **OTC Execution** — Accept large-volume OTC quotes by passing `type=OTC` **Best Practices** - Accept the quote immediately after confirming the rate to avoid expiry - Store the returned `orderId` for reconciliation and support queries ' operationId: convert_accept_quote 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: - quoteId - timestamp - signature properties: quoteId: type: string description: The quote ID returned from the Get Quote endpoint. example: q_abc123 type: type: string enum: - CONVERT - LIGHTNING - LIGHTNING_WITHDRAW - OTC description: "Conversion type. Must match the type used when fetching the quote.\n\n- `CONVERT` — Standard Convert mode (default)\n- `LIGHTNING` — Lightning Convert mode\n- `LIGHTNING_WITHDRAW` — Lightning Withdraw mode\n- `OTC` — OTC-Convert mode (whitelist-only feature, minimum trade size $20,000;\n contact otcdesk_ph@coins.ph to request access)\n" 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 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: Accept Quote source: 'curl --location ''https://api.pro.coins.ph/openapi/convert/v1/accept-quote'' \ --header ''X-COINS-APIKEY: your_api_key'' \ --data-urlencode ''quoteId=q_abc123'' \ --data-urlencode ''timestamp=1700000000000'' \ --data-urlencode ''signature=your_signature'' ' responses: '200': description: Quote accepted and conversion initiated. content: application/json: schema: type: object properties: orderId: type: string description: The order ID for the accepted conversion. example: ord_xyz789 status: type: string enum: - TODO - PROCESSING - SUCCESS - FAILED description: 'The order status. Possible values are: `TODO`, `PROCESSING`, `SUCCESS`, and `FAILED`. `TODO` means the order is ready to process (pending execution). `PROCESSING` means the server is processing the order. `SUCCESS` means the order has been completed successfully. `FAILED` means the order processing failed. Please check the `errorMessage` field in the Order List API response for the detailed failure reason. ' example: SUCCESS examples: success: summary: Quote accepted value: orderId: ord_xyz789 status: SUCCESS default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | 10000003 | Too many requests. Try again later. (This endpoint supports a minimum refresh interval of 1000 ms) | For the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes). ' /openapi/convert/v1/query-order-history: post: tags: - Convert summary: Retrieve Order History (USER_DATA) description: 'Query the history of convert orders for the authenticated account. **Key Notes** - Maximum query window is 180 days. - Default page size is 10; maximum is 200 records per page. --- ## 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) - **Conversion Audit** — Review all past conversions for a given time period - **Reconciliation** — Match convert orders against balance changes for accounting **Best Practices** - Use `startTime` and `endTime` to narrow queries and avoid fetching large datasets - Filter by `status=PROCESSING` to identify orders that may need follow-up - Paginate using `page` and `size` rather than fetching all records at once ' operationId: convert_query_order_history 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: - timestamp - signature properties: startTime: type: integer format: int64 description: Start time filter in Unix milliseconds. endTime: type: integer format: int64 description: End time filter in Unix milliseconds. status: type: string enum: - TODO - PROCESSING - SUCCESS - FAILED description: 'Filter by order status. Possible values: `TODO`, `PROCESSING`, `SUCCESS`, `FAILED`. Please refer to [accept-quote API → order status] for the description of each status.' page: type: integer description: 'Page number for pagination. Default: 1.' example: 1 size: type: integer description: 'Number of records per page. Default: 10, maximum: 200.' example: 10 type: type: string enum: - CONVERT - LIGHTNING - LIGHTNING_WITHDRAW - OTC description: Specifies the trading mode. Please refer to [get-quote API → type]. quoteId: type: string description: Filter by quote ID. Please refer to [accept-quote API → quoteId]. orderId: type: string description: Filter by order ID. Please refer to [accept-quote API → orderId]. 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 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: Query Order History source: 'curl --location ''https://api.pro.coins.ph/openapi/convert/v1/query-order-history'' \ --header ''X-COINS-APIKEY: your_api_key'' \ --data-urlencode ''page=1'' \ --data-urlencode ''size=10'' \ --data-urlencode ''timestamp=1700000000000'' \ --data-urlencode ''signature=your_signature'' ' responses: '200': description: List of convert order history records. content: application/json: schema: type: object properties: total: type: integer description: Total number of records matching the query. example: 25 data: type: array items: type: object properties: id: type: string description: Unique record ID. example: '12345' orderId: type: string description: Order ID generated by the server. Please refer to [accept-quote API → orderId]. example: ord_xyz789 quoteId: type: string description: Order reference quote Id. Please refer to [accept-quote API → quoteId]. example: q_abc123 sourceCurrency: type: string description: Source currency of the conversion. example: PHP targetCurrency: type: string description: Target currency of the conversion. example: BTC sourceAmount: type: string description: Source amount converted. example: '5000' targetAmount: type: string description: Target amount received. example: '0.00142857' price: type: string description: Exchange rate applied. example: '3500000' status: type: string enum: - TODO - PROCESSING - SUCCESS - FAILED description: 'Order status. Possible values: `TODO` (ready to process), `PROCESSING`, `SUCCESS`, `FAILED`. Please refer to [accept-quote API → order status] for the description of each status.' example: SUCCESS createdAt: type: integer format: int64 description: Order creation time in Unix milliseconds. example: 1700000000000 errorMessage: type: string description: Error message if the order failed. example: '' errorCode: type: string description: Error code if the order failed. example: '' inversePrice: type: string description: Inverse price (targetCurrency to sourceCurrency). example: '0.00000029' examples: success: summary: Order history result value: total: 25 data: - id: '12345' orderId: ord_xyz789 quoteId: q_abc123 sourceCurrency: PHP targetCurrency: BTC sourceAmount: '5000' targetAmount: '0.00142857' price: '3500000' status: SUCCESS createdAt: 1700000000000 errorMessage: '' errorCode: '' inversePrice: '0.00000029' default: description: 'API error response. The `code` field contains the internal API error code (not an HTTP status code). | Code | Description | |---|---| | -1100 | Illegal characters found in parameter | 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