Kaskade Payment Solution API

The Kaskade Payment Solution API lets you accept and send cryptocurrency from your own app or backend. Price in USD, let customers pay in 23 coins across 14 networks, reconcile with signed webhooks, and pay out to external wallets — all behind one stable, JSON-over-HTTPS contract.

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

The current version is v1, pinned in the URL path. 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) would only ship under a new prefix such as /api/v2, and v1 would keep running. Material changes are listed in the dashboard changelog.

Quick start

1. Create an API key. In your dashboard, open Developers 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.

• 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, players and both ramp endpoints. It is optional — omit it and nothing changes.

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.

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 23 coins across 14 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.

Coming soon — not yet transactional

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

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 four networks here, so "usdt" on its own names nothing and is refused. Use the identifier from GET /currencies — usdttrc20 (Tron), usdterc20 (Ethereum), usdtbsc (BNB Chain), usdtton (TON).

{
  "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.

The shipped equivalent is Players: a permanent deposit address per customer, attributed to your own identifier. See that section for the real contract.

The payout object Live

A payout sends crypto from your balance to a destination you have already registered. 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.

Webhooks

Set a webhook URL in your dashboard; we POST an event every time a payment 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 or data.deposit — never a top-level resource key. id is stable per object and transition, which makes it the natural key for de-duplicating retries.

Players — permanent deposit addresses

A player is one of your customers with a permanent deposit address. Anything sent to it is attributed to that player and reported to you by webhook — the building block for pay-by-name and account-funding flows.

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 document can generate a typed client in your language with the generator you already use.

Postman collection

Import the collection to call every endpoint with your key pre-wired. It includes a baseUrl variable and an apiKey variable — set them once and go.

Download collection (.json)

In Postman: Import → Upload Files → select the file, then set the collection variables baseUrl 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, and enable request signing per key. 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 Settings → 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 Payment history and click Export CSV 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?

Create a small live payment (e.g. $5+) and pay it on-chain, or reach out for sandbox access.

Which status means “paid”?

finished. Fulfil orders on that webhook, idempotently.