{"openapi":"3.1.0","info":{"title":"CoinsFlow Payments API","version":"1.3.0","description":"Create crypto invoices on Bitcoin, Litecoin, Ethereum, BNB Smart Chain and TRON (including USDT and USDC), send customers to a hosted payment page, track payments, withdraw, and receive signed webhooks. All amounts are decimal strings. Webhook requests carry CoinsFlow-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(endpoint secret, \"<t>.<raw body>\")>.","contact":{"name":"CoinsFlow","url":"https://coinspath.net"}},"servers":[{"url":"https://api.coinspath.net","description":"Production"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Merchant API key, \"cf_live_<prefix>_<secret>\". Create one at https://coinspath.net/apis/dashboard."}},"schemas":{"Withdrawal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"chain":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]},"asset":{"type":"string","enum":["BTC","LTC","ETH","BNB","TRX","USDT","USDC"]},"destination":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"What the destination receives."},"fee":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Fee in the same asset, taken from the balance on top of amount. Covers every network cost of the withdrawal."},"total":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"amount + fee: what leaves your balance."},"status":{"type":"string","enum":["requested","approved","signing","broadcast","confirmed","failed","cancelled","stuck"]},"txid":{"type":["string","null"]},"networkFee":{"type":["string","null"],"description":"Network fee the platform paid, in networkFeeAsset."},"networkFeeAsset":{"type":["string","null"]},"confirmations":{"type":"integer"},"confirmationsRequired":{"type":"integer"},"usdValue":{"type":["string","null"]},"orderRef":{"type":["string","null"]},"failureReason":{"type":["string","null"],"description":"Plain-language reason for failed, cancelled or stuck."},"statusNote":{"type":["string","null"],"description":"Plain-language explanation while a withdrawal takes longer than usual; otherwise null."},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"broadcastAt":{"type":["string","null"],"format":"date-time"},"confirmedAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"}}},"CreateWithdrawal":{"type":"object","required":["chain","asset","amount","destination"],"properties":{"chain":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]},"asset":{"type":"string","enum":["BTC","LTC","ETH","BNB","TRX","USDT","USDC"]},"amount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,18})?$","example":"250"},"destination":{"type":"string","minLength":20,"maxLength":100,"description":"Validated with the network's checksum."},"maxFee":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,18})?$","description":"The highest fee you accept (from a quote). If the fee is higher now, nothing is created: 409 fee_changed."},"orderRef":{"type":"string","maxLength":255}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["invoice.detected","invoice.confirming","invoice.paid","invoice.underpaid","invoice.overpaid","invoice.settled","invoice.expired","invoice.cancelled","withdrawal.broadcast","withdrawal.confirmed","withdrawal.failed"]}},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"secret":{"type":"string","description":"Only when creating or rotating. whsec_…"},"secretHint":{"type":"string"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"lastFailureAt":{"type":["string","null"],"format":"date-time"},"failingSince":{"type":["string","null"],"format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"unsupported_asset"},"detail":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"CreateInvoice":{"type":"object","required":["chain","asset"],"description":"Give exactly one of `amount` (crypto) or `priceAmount` (USD).","properties":{"chain":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]},"asset":{"type":"string","enum":["BTC","LTC","ETH","BNB","TRX","USDT","USDC"]},"amount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,18})?$","example":"0.015","description":"Exact crypto amount, at most the asset's decimals. Never a JSON number."},"priceAmount":{"type":"string","pattern":"^\\d{1,10}(\\.\\d{1,8})?$","example":"49.99","description":"USD price (under 10,000,000,000); converted at a rate locked on creation."},"priceCurrency":{"type":"string","enum":["USD"],"default":"USD"},"orderId":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":500},"ttlSeconds":{"type":"integer","minimum":60,"maximum":604800,"default":3600},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"Metadata":{"type":"object","maxProperties":20,"propertyNames":{"minLength":1,"maxLength":40},"additionalProperties":{"oneOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Your own key/value pairs, returned on the invoice. Never shown to the customer."},"Payment":{"type":"object","properties":{"txid":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Exact decimal string in whole units. Never a JSON number."},"confirmations":{"type":"integer"},"status":{"type":"string","enum":["mempool","confirming","confirmed","orphaned"],"description":"mempool: broadcast, not yet in a block (never counted). orphaned: reorganised out, or with blockHeight null, dropped from the mempool."},"blockHeight":{"type":["integer","null"]},"seenAt":{"type":"string","format":"date-time"}}},"Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"chain":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]},"asset":{"type":"string","enum":["BTC","LTC","ETH","BNB","TRX","USDT","USDC"]},"address":{"type":"string","description":"Fresh address for this invoice only."},"amountDue":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Exact decimal string in whole units. Never a JSON number."},"amountPaid":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Sum of payments included in a block."},"status":{"type":"string","enum":["new","pending","detected","confirming","underpaid","paid","overpaid","settled","expired","cancelled"]},"orderId":{"type":["string","null"]},"description":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"priceAmount":{"type":["string","null"],"description":"USD price, when the invoice was priced in USD."},"priceCurrency":{"type":"string"},"confirmationsRequired":{"type":"integer","description":"Confirmations at which it counts as paid. Lower for invoices worth at most $500 on Bitcoin (1) and Litecoin (2)."},"paidLate":{"type":"boolean"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"usdValue":{"type":["string","null"],"description":"USD value when created (reporting only)."},"paymentUrl":{"type":"string","format":"uri","description":"Hosted payment page for the customer."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"},"description":"Only on GET /v1/invoices/{id}."}}},"InvoicePage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"nextCursor":{"type":["string","null"]}}},"Balances":{"type":"object","properties":{"currency":{"type":"string","example":"USD"},"totalUsd":{"type":"string","example":"1234.56"},"assets":{"type":"array","items":{"type":"object","properties":{"chain":{"type":"string"},"chainName":{"type":"string"},"asset":{"type":"string"},"assetName":{"type":"string"},"decimals":{"type":"integer"},"pending":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Exact decimal string in whole units. Never a JSON number."},"payable":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Exact decimal string in whole units. Never a JSON number."},"total":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Exact decimal string in whole units. Never a JSON number."},"priceUsd":{"type":["number","null"]},"valueUsd":{"type":"string"},"allocation":{"type":"number"}}}}}}}},"paths":{"/v1/invoices":{"post":{"operationId":"createInvoice","summary":"Create an invoice","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Retries with the same key and body return the original invoice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoice"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"invalid_request, unsupported_asset or invalid_amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bad or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"merchant_inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_key_reuse, or idempotency_in_progress (a retry arrived while the first attempt was still running: retry shortly)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (50 requests/second per IP, bursts to 200)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"price_unavailable or chain_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listInvoices","summary":"List invoices, newest first","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"One status, or several comma-separated. One of: new, pending, detected, confirming, underpaid, paid, overpaid, settled, expired, cancelled.","example":"pending,detected,confirming"},{"name":"chain","in":"query","schema":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]}},{"name":"orderId","in":"query","schema":{"type":"string"},"description":"Exact order id."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Order id, the payment address, or the start of the invoice id."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"nextCursor from the previous page."}],"responses":{"200":{"description":"A page of invoices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePage"}}}},"400":{"description":"invalid_cursor or an unknown status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices/{id}":{"get":{"operationId":"getInvoice","summary":"Get an invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices/{id}/cancel":{"post":{"operationId":"cancelInvoice","summary":"Cancel an invoice before any payment is detected","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_cancellable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/balances":{"get":{"operationId":"getBalances","summary":"Balances per chain and asset","responses":{"200":{"description":"Balances","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balances"}}}}}}},"/v1/me":{"get":{"operationId":"getMerchant","summary":"The merchant this key belongs to","responses":{"200":{"description":"Merchant profile"}}}},"/chains":{"get":{"operationId":"getChains","summary":"Which networks are taking payments right now (no auth)","security":[],"responses":{"200":{"description":"{ chains: [{ chain, name, assets, status: ok|delayed|offline|unavailable, acceptingPayments, height, lastBlockAt, checkedAt }] }"}}}},"/prices":{"get":{"operationId":"getPrices","summary":"Latest USD price per asset, for display (no auth)","security":[],"responses":{"200":{"description":"{ currency: \"USD\", rates: { BTC: \"84125.0\", ... }, updatedAt }"}}}},"/v1/withdrawals/quote":{"get":{"operationId":"quoteWithdrawal","summary":"Fee, minimum and maximum for a withdrawal right now","description":"The fee covers every network cost of the withdrawal, including transactions that bring funds together first. With amount (and destination) it is the exact fee a withdrawal made now is charged; without, the lowest fee (one transaction).","parameters":[{"name":"chain","in":"query","required":true,"schema":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]}},{"name":"asset","in":"query","required":true,"schema":{"type":"string","enum":["BTC","LTC","ETH","BNB","TRX","USDT","USDC"]}},{"name":"amount","in":"query","schema":{"type":"string"},"description":"The amount to send, decimal string."},{"name":"destination","in":"query","schema":{"type":"string"},"description":"Where it will go (TRON: a first-time receiver costs more)."}],"responses":{"200":{"description":"{ chain, asset, available, amount?, fee, feeUsd, feeSource, networkTransactions, minAmount, withdrawable, maxAmount, confirmationsRequired }"},"400":{"description":"invalid_chain, unsupported_asset, invalid_amount or invalid_destination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/withdrawals":{"post":{"operationId":"createWithdrawal","summary":"Withdraw settled balance (key needs the withdrawals permission and an IP allowlist)","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body returns the original withdrawal."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithdrawal"}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"description":"invalid_request, unsupported_asset, invalid_destination, amount_too_small or insufficient_balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"scope_required, ip_not_allowed, withdrawals_disabled or merchant_inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"fee_changed (the fee is above maxFee), idempotency_key_reuse or idempotency_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"withdrawals_paused, chain_unavailable or rates_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listWithdrawals","summary":"List withdrawals, newest first","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"One or several comma-separated: requested, approved, signing, broadcast, confirmed, failed, cancelled, stuck."},{"name":"chain","in":"query","schema":{"type":"string","enum":["bitcoin","litecoin","ethereum","bsc","tron"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data: Withdrawal[], nextCursor }"}}}},"/v1/withdrawals/{id}":{"get":{"operationId":"getWithdrawal","summary":"Get a withdrawal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The withdrawal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/withdrawals/{id}/cancel":{"post":{"operationId":"cancelWithdrawal","summary":"Cancel while requested or approved","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_cancellable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"listWebhookEndpoints","summary":"Webhook endpoints","responses":{"200":{"description":"{ data: WebhookEndpoint[], events: string[] }"}}},"post":{"operationId":"createWebhookEndpoint","summary":"Add an endpoint (https, public). Returns its signing secret.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["invoice.detected","invoice.confirming","invoice.paid","invoice.underpaid","invoice.overpaid","invoice.settled","invoice.expired","invoice.cancelled","withdrawal.broadcast","withdrawal.confirmed","withdrawal.failed"]}},"description":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"invalid_url, invalid_events or limit_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}":{"patch":{"operationId":"updateWebhookEndpoint","summary":"Change url, events, description or enabled","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Remove an endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ deleted: true }"}}}},"/v1/webhooks/{id}/test":{"post":{"operationId":"testWebhookEndpoint","summary":"Queue a ping event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"{ deliveryId }"}}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","summary":"New signing secret; the old one stops working","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"With the new secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"Recent deliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"{ data: [{ id, event, refId, attempts, lastStatus, lastError, state, deliveredAt, nextRetryAt, createdAt, durationMs, response, payload }] }"}}}},"/v1/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"operationId":"retryWebhookDelivery","summary":"Send a delivery again now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"{ queued: true }"}}}},"/status":{"get":{"operationId":"getStatus","summary":"Platform status (no auth)","security":[],"responses":{"200":{"description":"{ status: operational|partial|degraded, updatedAt, components: [{ id, name, status }], chains: [{ chain, name, status, height, lastBlockAt }] }"}}}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Headline numbers for settled USD-priced invoices","responses":{"200":{"description":"Stats"}}}}}}