# CoinsFlow

CoinsFlow is a self-hosted crypto payment gateway and Litecoin block explorer.
Merchants create invoices through a REST API and send customers to a hosted payment
page. Supported: Bitcoin (BTC), Litecoin (LTC), Ethereum (ETH, USDT, USDC), BNB Smart
Chain (BNB, USDT, USDC) and TRON (TRX, USDT, USDC). The explorer covers Litecoin.

## Payments API

Base URL: https://api.coinspath.net
Auth:     Authorization: Bearer cf_live_<prefix>_<secret>
Keys:     https://coinspath.net/apis/dashboard (one key per merchant, shown once)
Format:   JSON. Send Content-Type: application/json with a body.
Amounts:  ALWAYS decimal strings ("0.015"), never JSON numbers.
Fee:      0.5% per received payment. No monthly fee.

### POST /v1/invoices
Create an invoice with a fresh address. Body: chain (bitcoin|litecoin|ethereum|bsc|tron),
asset (BTC|LTC|ETH|BNB|TRX|USDT|USDC, must exist on the chain), and exactly one of
amount (crypto, decimal string) or priceAmount (USD, up to 8 decimals; rate locked on creation).
Optional: orderId, description, ttlSeconds (60-604800, default 3600), metadata (up to 20
key/value pairs, returned on reads, never shown to the customer).
Header Idempotency-Key (1-200 chars) makes retries safe, even concurrent ones (409
idempotency_in_progress while the first is running). Returns 201 with the invoice, including paymentUrl.

    curl https://api.coinspath.net/v1/invoices \
      -H "Authorization: Bearer $COINSFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: order-1042" \
      -d '{"chain":"tron","asset":"USDT","priceAmount":"49.99","orderId":"order-1042"}'

### GET /v1/invoices/{id}
Current state plus payments[] (txid, amount, confirmations, status mempool|confirming|confirmed|orphaned,
blockHeight, seenAt). Fulfil when status is paid, overpaid or settled.

### GET /v1/invoices?status=&chain=&orderId=&q=&limit=&cursor=
Newest first. status takes one value or several comma-separated. Follow nextCursor until it is null.

### POST /v1/invoices/{id}/cancel
Only before any payment is detected; otherwise 409 not_cancellable.

### GET /v1/balances
Per (chain, asset): pending (credited, not final) and payable (final, withdrawable).

### GET /v1/me, GET /v1/stats
Merchant profile; headline numbers.

### GET /chains, GET /prices, GET /status (no auth)
Network status (invoices are refused with 503 chain_unavailable unless status is ok), USD prices,
and overall platform status.

### Withdrawals
GET /v1/withdrawals/quote?chain=&asset=&amount=&destination= -> fee, networkTransactions, minAmount,
  withdrawable, maxAmount. With amount (and destination) the fee is exact. The fee covers every
  network cost of the withdrawal, including transactions that bring funds together first.
POST /v1/withdrawals {chain, asset, amount, destination, maxFee?, orderRef?} (+ Idempotency-Key header)
  -> 201 status "requested". amount is what arrives; fee is taken from the balance on top.
  maxFee (from the quote): a higher fee now is refused with 409 fee_changed, nothing created.
  Needs a key with the withdrawals permission AND an IP allowlist (set in the dashboard,
  requires 2FA). Otherwise 403 scope_required / ip_not_allowed.
GET /v1/withdrawals/{id}, GET /v1/withdrawals?status=&chain=&limit=&cursor=,
POST /v1/withdrawals/{id}/cancel (only while requested or approved).
Statuses: requested -> approved -> signing -> broadcast -> confirmed; failed (refunded),
cancelled, stuck (being resolved; never auto-refunded). Minimums: BTC 0.0002, LTC 0.01,
ETH 0.002, BNB 0.005, TRX 20, USDT 5, USDC 5.

### Webhooks
Manage with GET/POST /v1/webhooks, PATCH/DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test,
GET /v1/webhooks/{id}/deliveries, POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry,
POST /v1/webhooks/{id}/rotate-secret. Events: invoice.detected, invoice.confirming,
invoice.paid, invoice.underpaid, invoice.overpaid, invoice.settled, invoice.expired,
invoice.cancelled, withdrawal.broadcast, withdrawal.confirmed, withdrawal.failed.
Body: {id (delivery id, stable across retries), type, createdAt, previousStatus, data}.
Verify: header CoinsFlow-Signature "t=<unix>,v1=<hex>"; v1 = HMAC-SHA256(secret, "<t>.<raw body>").
Reject if |now - t| > 300 s. Reply 2xx within 10 s; retries at 3 s, 30 s, 5 min, 1 h, 6 h, 24 h.

## Invoice statuses
pending -> detected -> confirming -> paid (credited) -> settled (final, withdrawable).
detected: on bitcoin and litecoin, seconds after the customer sends (still in the mempool,
not counted); elsewhere, in its first block. A mempool payment dropped before mining
(replaced or double-spent) reopens the invoice (pending, or expired past the deadline).
Also: underpaid (top up to the same address), overpaid, expired (a late payment is still
credited, paidLate: true), cancelled. Every address we issue is watched permanently: money
sent to a cancelled or long-closed invoice is credited to the merchant as a deposit.
Confirmations to paid (invoice <= $500 / above) and to settled: bitcoin 1/2 and 6,
litecoin 2/6 and 12, ethereum 12 and 32, bsc 15 and 30, tron 20 and 40. Each invoice
carries its own confirmationsRequired.

## Errors
JSON { "error": "<code>", "detail": "<text>" }. Codes: invalid_request, unsupported_asset,
invalid_amount, invalid_cursor, unauthorized, merchant_inactive, not_found, idempotency_key_reuse,
idempotency_in_progress, not_cancellable, price_unavailable, chain_unavailable, internal_error,
invalid_destination, amount_too_small, insufficient_balance, scope_required, ip_not_allowed,
withdrawals_disabled, withdrawals_paused.
Rate limit: 50 requests/second per IP (bursts to 200), then HTTP 429.

## Not yet available
Bitcoin Lightning.

## Links
OpenAPI 3.1: https://coinspath.net/openapi.json
Docs:        https://coinspath.net/apis/docs
Explorer:    https://coinspath.net/explorer/litecoin