Coins.ph Coins Pro — Convert
Coins Pro — Convert API (TRADING v1.0.0) — part of the Coins.ph developer platform.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "TRADING",
"version": "1.0.0",
"description": "Convert endpoints for the Coins.ph Trading API — covering quote fetching and acceptance."
},
"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."
}
],
"x-tagGroups": [
{
"name": "TRADING",
"tags": [
"Convert"
]
}
],
"x-readme": {
"proxy-enabled": false
},
"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.\nEach pair includes the source and target currency, amount limits, and decimal precision.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 1\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Pre-conversion Validation** — Check if a desired currency pair is supported before requesting a quote\n- **Limit Discovery** — Retrieve min/max source amounts to validate input before submitting\n\n**Best Practices**\n\n- Cache the response and refresh periodically; supported pairs change infrequently\n- Use the `precision` field to format display amounts correctly for each pair\n- Filter by `sourceCurrency` or `targetCurrency` client-side to reduce UI clutter\n",
"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' \\\n--header 'X-COINS-APIKEY: your_api_key' \\\n--data-urlencode 'timestamp=1700000000000' \\\n--data-urlencode 'signature=your_signature'\n"
}
],
"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).\n\n| Code | Description |\n|---|---|\n| -1100 | Illegal characters found in parameter |\n| -1104 | Not all sent parameters were read |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/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.\n\nProvide either `sourceAmount` or `targetAmount`, but not both. The quote is valid\nfor the number of seconds specified in the `expiry` field of the response.\n\n**Key Notes**\n\n- The quote `quoteId` must be used with the Accept Quote endpoint before expiry.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 1\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **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.\n\n**Best Practices**\n\n- Fetch a new quote immediately before accepting; quotes expire quickly (see `expiry` field)\n- Use `sourceAmount` for fixed-spend conversions; use `targetAmount` for fixed-receive conversions\n- 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).\n",
"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' \\\n--header 'X-COINS-APIKEY: your_api_key' \\\n--data-urlencode 'sourceCurrency=PHP' \\\n--data-urlencode 'targetCurrency=BTC' \\\n--data-urlencode 'sourceAmount=5000' \\\n--data-urlencode 'timestamp=1700000000000' \\\n--data-urlencode 'signature=your_signature'\n"
}
],
"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).\n\n| Code | Description |\n|---|---|\n| -1100 | Illegal characters found in parameter |\n| -1102 | Mandatory parameter was not sent, was empty/null, or malformed |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/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\nis executed immediately upon acceptance.\n\n**Key Notes**\n\n- The `type` parameter, if provided, must match the type used in the Get Quote request.\n- Quotes expire after the number of seconds indicated by the `expiry` field in the quote response.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 1\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Instant Conversion** — Execute a currency swap immediately at the quoted rate\n- **Two-Step Convert Flow** — Combine with Get Quote to build a confirm-then-execute UX\n- **OTC Execution** — Accept large-volume OTC quotes by passing `type=OTC`\n\n**Best Practices**\n\n- Accept the quote immediately after confirming the rate to avoid expiry\n- Store the returned `orderId` for reconciliation and support queries\n",
"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' \\\n--header 'X-COINS-APIKEY: your_api_key' \\\n--data-urlencode 'quoteId=q_abc123' \\\n--data-urlencode 'timestamp=1700000000000' \\\n--data-urlencode 'signature=your_signature'\n"
}
],
"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`.\n`TODO` means the order is ready to process (pending execution).\n`PROCESSING` means the server is processing the order. `SUCCESS` means the order\nhas been completed successfully. `FAILED` means the order processing failed.\nPlease check the `errorMessage` field in the Order List API response for the\ndetailed failure reason.\n",
"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).\n\n| Code | Description |\n|---|---|\n| 10000003 | Too many requests. Try again later. (This endpoint supports a minimum refresh interval of 1000 ms) |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
},
"/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.\n\n**Key Notes**\n\n- Maximum query window is 180 days.\n- Default page size is 10; maximum is 200 records per page.\n\n---\n\n## Additional Info\n\n**Rate Limit** [📖 Learn More](https://api.docs.coins.ph/reference/general#api-limit-introduction)\n\nWeight: 1\n\n**Use Cases** [🧩 SDK](https://api.docs.coins.ph/reference/general#sdk)\n\n- **Conversion Audit** — Review all past conversions for a given time period\n- **Reconciliation** — Match convert orders against balance changes for accounting\n\n**Best Practices**\n\n- Use `startTime` and `endTime` to narrow queries and avoid fetching large datasets\n- Filter by `status=PROCESSING` to identify orders that may need follow-up\n- Paginate using `page` and `size` rather than fetching all records at once\n",
"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' \\\n--header 'X-COINS-APIKEY: your_api_key' \\\n--data-urlencode 'page=1' \\\n--data-urlencode 'size=10' \\\n--data-urlencode 'timestamp=1700000000000' \\\n--data-urlencode 'signature=your_signature'\n"
}
],
"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).\n\n| Code | Description |\n|---|---|\n| -1100 | Illegal characters found in parameter |\n\nFor the full list of error codes, see [Error Codes](https://api.docs.coins.ph/reference/error-codes).\n"
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-COINS-APIKEY"
}
}
}
}