Kaskade Payment Solution API

Infrastructure & stability

Kaskade Payment Solution is a contract-first API. The endpoints, fields and webhook events on this page are the product — the settlement engine behind them is an implementation detail that you never touch. Your keys are Kaskade Payment Solution keys, your objects are Kaskade Payment Solution objects, and your webhooks are signed with your Kaskade Payment Solution secret.

That separation is deliberate. Today settlement runs on a third-party custody provider; as volume grows we move to self-custody on an MPC platform (e.g. Fireblocks-class infrastructure) with our own on-chain wallets, treasury and payout signing. None of that changes a single request you make.The base URL, authentication, payment object, statuses and webhook payloads are guaranteed stable across that migration.

Base URL & environments

All endpoints are served over HTTPS from one versioned base URL. Plain HTTP is rejected.

https://kaskade.com/api/v1

Versioning & changelog

Two versions are live side by side, each pinned in the URL path: https://kaskade.com/api/v1 and https://kaskade.com/api/v2. V2 carries the newer capabilities — payouts with an explicit network-fee authorisation, customer deposit addresses, recipients and mass disbursements — and V1 keeps running unchanged; use both from the same key. Within a version we treat the following as backward-compatible and may ship them without a version bump:

• Adding new endpoints, optional request fields, or response fields.
• Adding new webhook event types or new enum values.
• Changing an endpoint's availability tag from Planned → Beta → Live.

Anything breaking (removing a field, changing a type) only ships under a new prefix, and the older version keeps running. One V1 operation has been superseded rather than changed: creating a payout (see Create a payout). Material changes are listed in the dashboard changelog.

Quick start

1. Create an API key. In your dashboard, open API Keys and create a key. Copy the secret — shown only once.
2. Create a payment. POST a USD price and the coin to pay in; you get a deposit address and the exact crypto amount.
3. Collect payment. Show the address (or our hosted page) to your customer.
4. Fulfil on webhook. Act when you receive a payment.updated event with status finished.

curl -X POST https://kaskade.com/api/v1/payments \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priceUsd": 50,
    "payCurrency": "btc",
    "orderId": "ORDER-123",
    "orderDescription": "Premium plan"
  }'

Which endpoint should I use?

Two endpoints create a request for money. They differ in who shows the payment page.

Both support the same two ways of saying how much, described in fiat mode vs coin mode below. Everything else — webhooks, statuses, settlement — is identical.

Pick a row

Fiat mode vs coin mode

Every request is priced in one of two things. The amount field you send isthe mode — there is no pricingMode to set.

USDT: always name the network

USDT is one name over several unrelated blockchains. A ticker here always encodes asset + network, so there is no separate network field to send — and "usdt" on its own is not valid, because it does not say which chain the money should arrive on.

usdttrc20 and usdterc20 are different rails and are never interchangeable. A TRC-20 request is only ever settled by USDT arriving on Tron, and an ERC-20 request only by USDT arriving on Ethereum; USDT sent on the other chain does not pay it. Get the exact spelling of any ticker from GET /currenciesrather than guessing.

Authentication

Every request must be authenticated. Two schemes grant the same access — use whichever fits your stack. Both work on V1 and V2. Some endpoints also need a scope on the key.

• Bearer key — simplest; send your secret key in a header.
• Request signing (HMAC) — strongest; sign each request so the key is never transmitted.

Errors & status codes

Conventional HTTP status codes; errors carry a human-readable error message. Most also carry a stable code to branch on, and a refusal caused by one input names it in field so you do not have to guess which value we rejected. Both are additive — read error alone if that is all you need.

{
  "error": "The invoice number is too long — 500 characters, and the most is 200.",
  "field": "orderId",
  "code": "validation_error"
}

Idempotency

To safely retry a POST without creating duplicates, send an Idempotency-Key header with a unique value (e.g. a UUID) per logical operation. We store the first response for 24 hours and replay it — byte for byte — for any retry with the same key and body. Replays carry Idempotent-Replay: true.

Idempotency-Key: 9f1c8a3e-1b2d-4c5f-8a90-abc123def456

Supported on every POST: payments, invoices, payouts, payout destinations, conversions and both ramp endpoints, where it is optional — omit it and nothing changes. On every V2 write it is required; a V2 write without one answers 400 idempotency_key_required.

If you cannot send the header, dedupe on your side using orderId, which we echo back on the payment.

Pagination

List endpoints return the most recent items (currently up to 100, newest first). Cursor pagination via limit and starting_after is on the roadmap. The shape below is our current intent, not a promise — do not build against it until it ships:

{
  "data": [ /* … items … */ ],
  "has_more": true,
  "next_cursor": "cmq7c0aa0000abc"
}

What you can rely on today: list responses return a plain array under a resource key (e.g. payments), newest first. That is the frozen V1 behaviour. A cursor envelope, if it ships, will be additive and will not change this response.

Cursor pagination exists today on GET /conversions (V1) and on the V2 lists. A V2 list answers { "data": [ … ], "hasMore": true }, newest first; pass limit and the id of the last item you received to get the next page. The parameter is starting_after on customer addresses and recipients, and startingAfter on disbursements.

Rate limits

Kaskade does not currently apply a documented per-key rate limit, and the API returns no X-RateLimit-* headers. There is no published quota to design against, and we would rather say that than publish a number we do not enforce.

Infrastructure in front of the API (our reverse proxy, and whatever sits in front of it) may still shed load under abuse or attack, so a well-behaved client should handle 429 and503 defensively — retry with exponential backoff and jitter — even though neither is part of a contract today.

A per-key limit with published headers may be introduced later. It will be announced in the changelog before it is enforced.

Currencies

Prices are set in USD and converted at a live rate. Customers can pay in any of the 7 coins across 4 networks below. Pass a coin's ticker as payCurrencywhen creating a payment; network-specific tickers select the chain. The live list is always GET /currencies.

Rates

Get a live conversion estimate before creating a payment — useful to preview the crypto amount a customer will owe for a given USD price.

Fees

Kaskade Payment Solution charges a transparent percentage on successful payments. Your effective rate and fee mode (absorb vs. add-on) are configured per account in the dashboard.

The payment object

A payment is a single request for funds. It is priced either in your base currency — the coin amount is then quoted at the live rate — or in the coin itself, in which case the payer owes exactly the amount you named. pricingMode says which.

Payment statuses

Partial payments & returns

With partial payments enabled on your account (ask us to switch it on), a payment can be paid in several transfers, cancelled, and returned to the wallet that sent it. status keeps the meaning above for every client; the precise picture is an optional p12 object on GET /v1/payments/:id and on every payment.updated event. Accounts without partial payments never receive it. Amounts are exact decimal strings in the payment's coin.

{
  "paymentState": "PARTIALLY_PAID",
  "requestedAmount": "100",
  "receivedAmount": "30",
  "remainingAmount": "70",
  "completionPercent": "30.00",
  "excessAmount": "0",
  "unacceptedAmount": "0",
  "excessDisposition": null,
  "meetsPartialMinimum": null,
  "partialDisposition": null,
  "depositCount": 1,
  "deposits": [{ "txHash": "a1b2…", "amount": "30", "senderAddress": "TQ…", "receivedAt": "2026-10-02T09:00:00.000Z" }],
  "multipleSenders": false,
  "cancelledAt": null,
  "returnState": "NONE",
  "returns": [],
  "event": "payment.partially_paid"
}

• Fulfil on paymentState: PAID or OVERPAID — the same moment status reads finished.
• The payer is asked for the rest. The hosted checkout shows what arrived and the exact amount still due, and its QR code carries that remainder.
• Partial minimum. If you set one, a partial below it is held out of your available balance until it is reached (then released automatically). If the payment expires or is cancelled first, a return to the payer is requested and reviewed by us; no platform fee is kept on money that goes back. You can accept a held partial instead — the platform fee then applies.
• Invoices collect several payments. A coin-priced invoice counts every payment raised for it: if the first payment window closes part-paid, opening the invoice again asks for exactly what is still due. The invoice reads partially_paid with amountReceived / amountRemaining, and invoice.updated fires on each change.
• Returns go only to the wallet a deposit came from, never to an address you supply. A refund of accepted funds is paid in full by you (the platform fee is not refunded); a return of unaccepted funds carries no platform fee.

Create a payment

Creates a payment and returns a deposit address and the exact crypto amount.

Two ways to say what the payment is for. Send exactly one.

• priceUsd — price it in your base currency. Kaskade quotes the coin amount at the live rate. This is the original behaviour and nothing about it has changed.
• payAmount — price it in the coin itself, as a decimal string. The payer owes exactly that amount and no exchange rate is involved in producing it.

Sending both, or neither, is a validation_error.

curl -X POST https://kaskade.com/api/v1/payments \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priceUsd": 50,
    "payCurrency": "btc",
    "orderId": "ORDER-123",
    "orderDescription": "Premium plan"
  }'

{
  "payment": {
    "id": "cmq7c1ab0000xyz",
    "npPaymentId": "4912345678",
    "priceUsd": 50,
    "payCurrency": "btc",
    "payAmount": 0.00052471,
    "payAddress": "bc1qexampleaddressxxxxxxxxxxxxxxxxxxxx",
    "payExtraId": null,
    "status": "waiting",
    "expiresAt": "2026-06-20T12:34:56.000Z",
    "pricingMode": "fiat",
    "requestedAmount": null,
    "requestedCurrency": null,
    "amountDueExact": "0.00052471"
  }
}

Pricing in the coin itself

Ask for a coin amount and that is exactly what the payer owes. Kaskade adds nothing to it: the platform fee comes out of your settlement, not out of the customer’s amount, whatever fee mode your account uses.

{
  "payAmount": "100",
  "payCurrency": "usdttrc20",
  "orderId": "ORDER-1001"
}

{
  "payAmount": "100",
  "payCurrency": "usdterc20",
  "orderId": "ORDER-1002"
}

{
  "payAmount": "0.005",
  "payCurrency": "btc",
  "orderId": "ORDER-1003"
}

{
  "payAmount": "0.25",
  "payCurrency": "eth",
  "orderId": "ORDER-1004"
}

The same request as a copy-paste call — 0.005 BTC, exactly:

curl -X POST https://kaskade.com/api/v1/payments \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payAmount": "0.005",
    "payCurrency": "btc",
    "orderId": "ORDER-1003"
  }'

The response carries the id, the payCurrency, the exact amountDueExact, the payAddress to send to, the status and the expiresAt deadline:

{
  "payment": {
    "id": "cmq7c1ab0000xyz",
    "npPaymentId": "fb_9f2c1d4e5a6b7c8d",
    "pricingMode": "crypto",
    "priceUsd": null,
    "requestedAmount": "100",
    "requestedCurrency": "usdttrc20",
    "payCurrency": "usdttrc20",
    "payAmount": 100,
    "amountDueExact": "100",
    "payAddress": "TExampleAddressxxxxxxxxxxxxxxxxxxxxx",
    "payExtraId": null,
    "status": "waiting",
    "expiresAt": "2026-06-20T12:34:56.000Z"
  }
}

The network is part of the coin identifier

USDT exists on more than one network, so "usdt" on its own names nothing and is refused. Use the identifier from GET /currencies — today usdttrc20 (Tron) and usdterc20 (Ethereum).

{
  "payAmount": "100",
  "payCurrency": "usdt"
}

→ 400
{
  "error": "USDT cannot be used to price a request in the coin itself. Price this one in your base currency instead, or choose another coin from GET /v1/currencies.",
  "field": "payCurrency",
  "code": "unsupported_asset"
}

What a coin-denominated payment does and does not do

• The payer owes the exact amount. 100 USDT means 100 USDT. Nothing is added on top and nothing is rounded off.
• It settles exactly. The 1% shortfall tolerance that applies to a rate-quoted payment does not apply here — 99.999999 of 100 USDT stays partially_paid. Fiat-priced payments are unchanged.
• It is payable only in the coin it is priced in. Kaskade does not convert between coins or across networks — see below.
• Amounts are decimal strings, not numbers. A JSON number cannot carry a coin amount intact, so payAmount must be quoted.
• Precision is the asset’s own, capped at 8 places in this release. USDT takes 6, BTC takes 8, and ETH — which carries 18 on chain — is accepted to 8 here. Anything finer is refused rather than silently rounded.
• expiresAt is when the request lapses, not when a rate lapses: an exact coin amount has no rate to expire.

{
  "payAmount": "0.0000001",
  "payCurrency": "usdttrc20"
}

→ 400
{
  "error": "USDTTRC20 amounts are accepted to at most 6 decimal places here, which is the chain's own precision.",
  "field": "payAmount",
  "code": "validation_error"
}

Same asset, same network — this release converts nothing

A coin-denominated request is settled by that asset on that network and by nothing else. Kaskade has no conversion engine in V1.1, so there is no rate at which a different coin could be accepted.

USDT that arrives on the wrong network is not lost — it is held in custody and an operator resolves it — but it does not settle the request, and the payment stays unpaid. Because the two USDT rails share a symbol and differ only in the ticker you send, this is the mistake worth guarding in your own integration: pass through the exact payCurrency you asked for rather than a display symbol.

Cross-asset and cross-network conversion is not part of V1.1. If you need a customer to pay in a coin of their choosing, price the request in fiat instead — that is what fiat mode is for.

List payments

Returns your most recent payments (up to 100), newest first.

curl https://kaskade.com/api/v1/payments \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY"

{
  "payments": [
    { "id": "cmq7c1ab0000xyz", "status": "finished", "priceAmount": 50, "payCurrency": "btc", "payInHash": "f4a1…", "createdAt": "2026-06-20T12:00:00.000Z" },
    { "id": "cmq7c0aa0000abc", "status": "waiting",  "priceAmount": 25, "payCurrency": "usdttrc20", "createdAt": "2026-06-20T11:40:00.000Z" }
  ]
}

Retrieve a payment

Fetches one payment by id and refreshes its status live before returning, so it always reflects the latest on-chain state.

curl https://kaskade.com/api/v1/payments/cmq7c1ab0000xyz \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY"

{
  "payment": {
    "id": "cmq7c1ab0000xyz",
    "status": "finished",
    "priceAmount": 50,
    "payCurrency": "btc",
    "payAmount": 0.00052471,
    "actuallyPaid": 0.00052471,
    "payAddress": "bc1qexampleaddressxxxxxxxxxxxxxxxxxxxx",
    "payInHash": "f4a1c9b2…",
    "createdAt": "2026-06-20T12:00:00.000Z"
  }
}

The invoice object Live

An invoice is a hosted, shareable request for payment. It produces a checkout URL your customer opens to pay in any supported coin, and emits the same payment.updated webhooks under the hood.

Get balances

Returns your available balance per coin.

curl https://kaskade.com/api/v1/balance \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY"

{
  "balances": {
    "btc": 0.01340000,
    "usdttrc20": 250.50
  }
}

Per-customer deposit addresses

Kaskade has no /wallets/addresses endpoint. An earlier version of this page published one as planned; it was never implemented, and it is not part of V1.

A payment gets its own deposit address. For a permanent address per customer — the same address every time, each transfer becoming its own payment — use V2 customer deposit addresses.

The payout object Live

A payout sends crypto from your balance to a destination you have already registered. Create one with Payout API v2; list and read them here. Creating one is a request, not a transfer: it is reviewed and released before anything reaches the chain, so treat status as the only statement about where the money actually is.

Payout status

The normal path is pending → approved → submitted → paid. A payout can leave that path at any point for rejected or failed.

Terminal: paid, rejected and failed. A payout in any of those three will not change again, so you can stop polling it. Success is paid and only paid. There is no sent status — earlier revisions of this page listed one and no such value has ever been returned by the API.

API v2 — overview & conventions

V2 is served from https://kaskade.com/api/v2 with the same keys and the same two authentication schemes as V1. It adds what V1's frozen shapes could not carry, and V1 keeps working beside it. The endpoint paths below are written from /api, so /v2/payouts/quote means https://kaskade.com/api/v2/payouts/quote.

The full machine-readable contract is the V2 OpenAPI document; the Postman collection includes every V2 request.

Payouts with a fee quote Live

The way to send a payout. Two calls: quote (reads only — reserves and sends nothing), then create against that quote with your fee authorisation. The key needs the payouts:write scope. Destinations, statuses, release and the payout.updated webhook are exactly those of the payout object.

Customer deposit addresses Live

A permanent deposit address per customer of yours and per coin. Asking again for the same customer and coin always returns the same address, and every transfer to it becomes its own payment for exactly the amount received — made for balance top-ups and repeat customers. Each such payment carries your customerId and the customerAddressId on the payment object and in payment.updated.

• Switched on per account (403 customer_addresses_not_enabled until then). Not available to accounts that settle straight to their own wallet (409 direct_settlement). No scope needed.
• Every deposit runs the normal payment path — screening, crediting, fees, settlement, returns. It is priced in the coin itself (pricingMode: crypto), reads confirming while final and screened, then finished. There is no quote to expire; the deposit is valued in your base currency on arrival, for fees and reports.
• Money that arrives is never refused. Switching the feature off stops new addresses, not deposits to existing ones.
• An address accepts its own coin only. Another asset sent to it is not credited automatically — contact support.

curl -X POST https://kaskade.com/api/v2/customer-addresses \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY" \
  -H "Idempotency-Key: addr-user_8812-usdttrc20" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "user_8812", "payCurrency": "usdttrc20", "label": "Jane Doe" }'

{
  "customerAddress": {
    "id": "cmh7a…",
    "customerId": "user_8812",
    "payCurrency": "usdttrc20",
    "network": "Tron",
    "address": "TXa9…f3",
    "tag": null,
    "label": "Jane Doe",
    "status": "ACTIVE",
    "createdAt": "2026-10-06T12:00:00.000Z"
  }
}

Newest first. Query: customerId (one customer's addresses), limit(1–100, default 50), starting_after. Answers { "data": [ … ], "hasMore": false }.

One of your addresses; another account's id is 404.

Public addresses Live

Your own permanent deposit address per coin, for anyone to pay to — publish it on a page, an invoice footer or a donation box. One is created automatically for every coin your account accepts (within minutes of the feature being switched on, or of you accepting a new coin); asking for a coin always returns the same address, and every transfer to it becomes its own payment for exactly the amount received, with the publicAddressId on the payment object and in payment.updated. The same rules as customer addressesapply (normal fees, screening and settlement), except that every account has them — no switch to request — plus:

• Who paid is not known. The payment carries the sending wallet only (customerId is null). A refund can only go back to that wallet.
• Transfers below the coin's payment minimum are not credited — a published address attracts dust. They stay in custody; contact support if one was real.

curl -X POST https://kaskade.com/api/v2/public-addresses \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY" \
  -H "Idempotency-Key: public-usdttrc20" \
  -H "Content-Type: application/json" \
  -d '{ "payCurrency": "usdttrc20" }'

{
  "publicAddress": {
    "id": "cmh9p…",
    "payCurrency": "usdttrc20",
    "network": "Tron",
    "address": "TQm4…8k",
    "tag": null,
    "status": "ACTIVE",
    "createdAt": "2026-10-19T12:00:00.000Z"
  }
}

Every coin's address, oldest first: { "data": [ … ] }. Errors are those of customer addresses.

Recipients Live

Your payees — customers, vendors, partners — one record each, keyed by your own reference, with the wallets each may be paid at. They are what disbursements pay. (Your own business wallets are payout destinations, not recipients.) Switched on per account (403 recipients_not_enabled); scopes recipients:read / recipients:write.

201 creates it. The same reference with identical details answers 200 with the existing recipient — safe to repeat; with different details, 409 recipient_exists: a payee's identity is never overwritten.

Newest first; limit (1–100, default 25), starting_after, and ref to find one by your reference. Addresses are not included in the list.

The recipient with its addresses.

{
  "address": {
    "id": "cma1…",
    "recipientId": "cmr9…",
    "coin": "usdttrc20",
    "network": "tron",
    "address": "TQ…",
    "tag": null,
    "ownershipType": "CUSTOMER_OWNED",
    "label": "main wallet",
    "status": "REVIEW_REQUIRED",
    "rejectReason": null,
    "screening": "NOT_SCREENED",
    "payable": false,
    "firstUsedAt": null,
    "lastUsedAt": null,
    "createdAt": "2026-10-14T12:00:00.000Z",
    "updatedAt": "2026-10-14T12:00:00.000Z"
  }
}

Addresses are reviewed by Kaskade. An account can instead choose, in the dashboard (Mass payouts → Settings, with an authenticator code), to approve its new recipient wallets automatically; every disbursement is still screened. The recipient.address.* webhooks tell you when a review ends.

Disbursements Live

A disbursement pays an approved recipient address from your balance. It is a payout underneath, with every payout control: quote, explicit fee authorisation, balance and fee reserve, screening, destination policy, risk tier and limits. Switched on per account (403 disbursements_not_enabled); scopes disbursements:read / disbursements:write. The recipient always receives the full amount; the network fee is yours.

{ "recipientAddressId", "amount", "feeAsset"? } → { quote }, the same shape as a payout quote plus recipientAddressId. Reads only; single use; about 3 minutes.

{
  "disbursement": {
    "id": "po_9d0e…",
    "object": "disbursement",
    "status": "PENDING",
    "recipientAddressId": "cma1…",
    "recipientId": "cmr9…",
    "merchantRecipientRef": "cust-001",
    "asset": "usdttrc20",
    "amount": "25",
    "recipientReceives": "25",
    "address": "TQ…",
    "reference": "PAYOUT-2026-10-14-1",
    "txHash": null,
    "error": null,
    "quoteId": "pq_77c0…",
    "batch": null,
    "networkFee": { "paidBy": "merchant", "settlementAsset": "usdttrc20", "reserved": "3", "actual": null, "settled": false },
    "createdAt": "2026-10-14T12:00:00.000Z",
    "completedAt": null
  }
}

Newest first; limit, startingAfter and batchId.

Disbursements raise disbursement.* webhooks, not payout.updated.

Mass disbursements Live

Pay many wallets in one action: send the rows over the API (or upload a CSV in the dashboard). Each row becomes an ordinary disbursement — a batch adds no new way for money to leave, only a way to prepare and authorise many at once. Same switch and scopes as disbursements.

1. Create. POST /v2/disbursements/batches with rows. Nothing is reserved or sent. Each row is { coin, address, amount, tag?, reference?, recipientRef?, recipientName?, recipientType? }. An address not yet on file is registered as a recipient address and goes to review.
2. Validate. Every row gets a verdict — READY, WAITING_ADDRESS_REVIEW, REJECTED_ADDRESS or INVALID — and the batch shows, per asset, the total, the estimated and suggested maximum fee per row, what is needed and what is spendable. Large batches finish in the background (VALIDATING → VALIDATED); POST …/validate continues it.
3. Approve. By default a person approves in the dashboard with an authenticator code. The approval covers the reviewed batchHash, a mode (send_ready_now or wait_for_all), a maximum network fee per row for each asset, and requires the whole batch to fit your spendable balance. It is valid for 72 hours.
4. Pay. Rows become disbursements one by one, each with its own reservation, screening and limits. A row whose fee exceeds the approved maximum, or that no longer fits the balance, fails on its own; the rest continue.

The batch and its rows; filter rows with status, page with afterRow and limit (1–500, default 100).

Cancels every row not yet turned into a disbursement. Disbursements already created are not recalled.

Automatic API approval only. Kaskade can allow your account to approve its own batches from your system; you then choose it in the dashboard (Mass payouts → Settings, with an authenticator code). The call takes { "batchHash", "mode", "feeCaps": { "usdttrc20": "2.5" } } and runs the same checks as a person's approval. Without both switches it answers 403 approval_requires_panel.

Conversions

Convert a balance from one asset into another — either on request, or automatically when a customer pays in something other than your settlement asset. The rate, our fee, the trading cost and the network cost are always reported separately; none of them is folded into the rate.

Enabled per account. Conversion is switched on for a merchant, a pair and a network, with caps. Until it is enabled for yours these endpoints answer 409 conversion_disabled, and your payments settle in the asset they were paid in — exactly as they do today.

Scopes. Reading needs conversions:read; creating needs conversions:write, which includes read. Keys have neither until Kaskade grants them (see scopes), and read never implies write.

The fee. The default Kaskade conversion service fee is 1.00% of the gross proceeds, in the destination asset, rounded down to that asset's precision. Your commercial agreement may set another rate. It is charged only when a conversion actually executes.

Costs, and who pays them. The provider trading fee, the source network fee, the venue withdrawal fee and the return network fee are each allocated to you or to Kaskade by your effective commercial policy — they are not always yours. Every quote and every conversion includes an economics object with the service fee, each cost, its payer, the totals you and Kaskade bear, and your net amount. A conversion keeps the policy it was created under. Slippage is not a fee.

Minimums and availability. Minimums and maximums belong to each route (see Available routes). A conversion below its route's minimum is refused with 400 conversion_below_minimum, above its maximum with 400 conversion_above_maximum. Some conversions may also be unavailable below configured economic thresholds for your account; those are refused with 400 conversion_uneconomic at the quote and at creation, before anything is reserved. A larger amount may be accepted.

Statuses. PENDING, APPROVED_FOR_EXECUTION, the in-flight states, then one of COMPLETED, HELD (a person is looking at it; your balance stays reserved), FAILED or RECOVERED (the source came back to you). Only COMPLETED means the destination asset is yours.

Webhooks

Set a webhook URL in your dashboard; we POST an event every time a payment — or a payout, conversion, recipient address, disbursement or batch — changes status. This is the reliable way to know when to fulfil — never rely on the customer's browser returning.

{
  "id": "evt_cmq7c1ab0000xyz_finished",
  "event": "payment.updated",
  "created": "2026-08-19T12:00:00.000Z",
  "data": {
    "payment": {
      "id": "cmq7c1ab0000xyz",
      "status": "finished",
      "orderId": "ORDER-123",
      "priceAmount": 50,
      "payCurrency": "btc",
      "payAmount": 0.001,
      "payInHash": "f4a1c9b2…",
      "pricingMode": "fiat",
      "requestedAmount": null,
      "requestedCurrency": null,
      "amountDueExact": "0.001"
    }
  }
}

Telling the two pricing modes apart. A coin-denominated payment carries pricingMode: "crypto" with requestedAmount and requestedCurrency set — so "100 USDT-TRON was requested and 100 USDT-TRON arrived" is distinguishable from "$100 was requested and roughly that much USDT arrived". In coin mode priceAmount is Kaskade's fiat reference valuation at creation, recorded for your reports; it is not what anyone was asked for. These fields appear on events raised from V1.1.0 onward; a redelivered older event replays its original bytes unchanged.

Every event uses this envelope: id, event, created, and the object nested under data. Read data.payment, data.invoice, data.payout, data.conversion, data.recipientAddress (with data.recipient), data.disbursement or data.batch — never a top-level resource key. id is stable per object and transition, which makes it the natural key for de-duplicating retries.

Fiat ramp

Let a customer buy crypto with a card or bank transfer (on-ramp), or sell it back to fiat (off-ramp). Kaskade creates the order with our ramp partner and returns a hosted checkout URL to redirect the customer to; they complete KYC and payment there.

Client libraries

Kaskade does not publish official SDKs today, and none is scheduled. We would rather say that than name packages you cannot install.

The API is plain HTTPS and JSON with bearer auth, so it needs no client library: the code examples below are copy-paste ready, the Postman collection covers every endpoint, and the OpenAPI documents ( V1, V2) can generate a typed client in your language with the generator you already use.

Postman collection

Import the collection to call every V1 and V2 endpoint with your key pre-wired. It includes baseUrl, baseUrlV2 and apiKey variables — set them once and go. V2 requests sit in folders marked v2 and carry a generated Idempotency-Key.

Download collection (.json)

In Postman: Import → Upload Files → select the file, then set the collection variables baseUrl, baseUrlV2 and apiKey.

Code examples

Create a payment

curl -X POST https://kaskade.com/api/v1/payments \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priceUsd": 50,
    "payCurrency": "btc",
    "orderId": "ORDER-123",
    "orderDescription": "Premium plan"
  }'

Authenticate with request signing

import crypto from "crypto";

const clientId     = "YOUR_CLIENT_ID";   // = your key's Public ID
const clientSecret = "ks_sk_YOUR_CLIENT_SECRET";         // shown once when you enable signing

const method = "POST";
const url    = "https://kaskade.com/api/v1/payments";        // the full URL, exactly as called
const ts     = new Date().toISOString();
const body   = JSON.stringify({ priceUsd: 50, payCurrency: "btc", orderId: "ORDER-123" });

// canonical = BOM + METHOD + URL + clientId + timestamp + body
const canonical = "\ufeff" + method + url + clientId + ts + body;
const signature = crypto.createHmac("sha256", clientSecret)
  .update(canonical, "utf8").digest("base64");

const res = await fetch(url, {
  method,
  headers: {
    "Content-Type": "application/json",
    "X-Kaskade-Client": clientId,
    "X-Kaskade-Timestamp": ts,
    "X-Kaskade-Signature": signature,
  },
  body,
});

Verify a webhook

import crypto from "crypto";

// Express raw-body handler for POST /webhooks/kaskade
app.post("/webhooks/kaskade", (req, res) => {
  const signature = req.headers["x-kaskade-signature"];
  const expected = crypto
    .createHmac("sha256", process.env.KASKADE_WEBHOOK_SECRET)
    .update(req.rawBody)            // the exact bytes we sent
    .digest("hex");

  if (signature !== expected) return res.status(401).end();

  const { event, payment } = JSON.parse(req.rawBody);
  if (payment.status === "finished") {
    // ✅ fulfil the order (idempotently)
  }
  res.status(200).end();
});

Integration options

There's more than one way to accept crypto with Kaskade Payment Solution — from sharing a link in seconds to wiring the full API into your platform. Pick the lightest option that meets your need; you can mix them, and they all settle to the same account and emit the same webhooks.

Plugins & platforms

Drop-in plugins let popular platforms accept crypto through Kaskade Payment Solution without custom code. Packaged plugins are rolling out; in the meantime every platform below can be wired up in minutes with the Create a payment endpoint and a webhook.

WooCommerce Planned

For WordPress + WooCommerce stores. The official gateway plugin (Planned) adds "Pay with crypto" at checkout, redirects the shopper to a hosted invoice, and marks the order paid on the invoice.paid webhook. Until it ships, integrate with a few lines in your theme or a small custom gateway:

1. Create an API key and set it in your server config (never in client JS).
2. On order placement, call POST /invoices with the order total as amountUsd and the WooCommerce order id as orderId.
3. Redirect the customer to the returned invoice url.
4. On the invoice.paid webhook (verify the signature), mark the matching order complete.

WHMCS Planned

For hosting and SaaS billing on WHMCS. The official payment-gateway module (Planned) registers Kaskade Payment Solution as a gateway so invoices can be paid in crypto and auto-reconciled. Manual integration mirrors WooCommerce: create a Kaskade Payment Solution invoice from the WHMCS invoice, send the client to the hosted checkout, and apply the payment when invoice.paid arrives (map by orderId = WHMCS invoice id).

Team & multi-user access

Most teams need more than one person — or service — touching the gateway. Here's how access works today and what's coming.

API keys as machine identities Live

Create a separate API key for each app, environment or service that talks to Kaskade Payment Solution. Keys are independent — name them ("production server", "staging", "billing worker"), rotate or revoke any one instantly without affecting the others, enable request signing per key, and ask for scopes only on the keys that need them. This is the practical way to give each part of your stack its own credential and audit trail.

Team seats & roles Live

Invite teammates to the dashboard from Team. Members are invited by email and set their own password from a single-use link. Each member carries a preset — admin, staff, viewer or custom — and the preset is only a label: actual access is a set of per-area permissions you tick, so custom is the honest choice whenever the presets do not fit. A member is invited, active or disabled, and disabling one keeps their audit trail.

Team seats are a dashboard feature. There is no V1 endpoint for managing them, and a team member is not an API credential — use a per-service API key for automation.

Export transaction history

Pull your payments for bookkeeping, reconciliation or accounting in two ways.

From the dashboard (CSV) Live

Open Payments and click Export all time to download your full payment history as a spreadsheet-ready file. Columns:

Via the API Live

For automated exports or syncing to your own ledger, page through List paymentsand persist what you need. Combine with webhooks to keep your records live instead of polling.

curl https://kaskade.com/api/v1/payments \
  -H "Authorization: Bearer ks_live_YOUR_API_KEY"

Migrating & support

Already integrated with another crypto gateway? Kaskade Payment Solution maps cleanly: a “create charge” becomes Create a payment, IPNs become webhooks, and your order reference rides along as orderId. Because the contract is provider-agnostic (see why), you integrate once and never re-migrate.

Stuck on something? Open a ticket from your dashboard or contact support.

FAQ

Do I need a separate key for signing?

No. Every API key can use Bearer auth, and you can additionally enable a signing secret on the same key.

What happens to my integration when you change crypto infrastructure?

Nothing. The contract on this page is stable across backend changes — see Infrastructure & stability.

How do I test without real money?

There is no sandbox or test mode today — every key is a live ks_live_ key. Test with a small live payment (e.g. $5+) paid on-chain, and check your signing code against the signing test vector before you send real requests.

Can I restrict an API key to my server's IP addresses?

Not today. See key scopes & access for how to protect a key instead.

How do I send a payout over the API?

With Payout API v2: quote, then create with your fee authorisation. The V1 create call is refused with fee_approval_required.

Which status means “paid”?

finished. Fulfil orders on that webhook, idempotently.