API reference
Call every endpoint from your server. Requests and responses are JSON. Webhook URLs and API keys are managed in the merchant dashboard.
Want working code to copy? Integration examples in Node.js, Python, PHP, Go and Java
| Endpoint | Purpose |
|---|---|
POST /v1/payment_intents | Create a payment intent |
GET /v1/payment_intents/{id} | Retrieve a payment intent |
POST /v1/deposit_addresses | Get a user's deposit address |
GET /v1/deposits | List deposits |
GET /v1/deposits/{id} | Retrieve a deposit |
GET /v1/chains | See the project's chains and tokens |
PUT /v1/customers/{external_id} | Add tags and notes to a user (optional) |
GET /v1/customers/{external_id} | Retrieve a user (optional) |
Conventions
| Base URL | https://api.kokiwa.com, for both mainnet and testnet. |
| Authentication | Header Authorization: Bearer sk_…. Keys starting with sk_live_ reach mainnet and keys starting with sk_test_ reach the testnet; their data is fully separate. A key can only reach its own project. |
| Amounts | Strings in token units, such as "25.00". Requests allow up to 6 decimal places; responses keep full on-chain precision, so the number of places varies. Only transaction.raw_amount is the raw on-chain value. |
| Times | ISO 8601 UTC, such as 2026-11-02T08:30:00Z. |
| Addresses | EVM addresses are returned in EIP-55 checksum format. Show them unchanged and ignore case when comparing. |
| Idempotency | POST requests can send Idempotency-Key (up to 255 characters). A retry with the same key returns the first result with the response header Idempotent-Replayed: true. |
Errors
Failures return 4xx or 5xx. Branch on code; message is for debugging only.
{
"error": {
"code": "amount_below_minimum",
"message": "options[0].amount is below the minimum",
"details": { "min_amount": "5.00" }
}
}| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_* | Invalid parameter; message names the field. |
| 400 | chain_not_enabled | The project has no active payout address on this chain, or has turned payments off there. |
| 400 | chain_not_available | This chain does not take payments right now. |
| 400 | chain_not_supported | This chain has no deposit addresses. |
| 400 | token_not_enabled | The project has not selected this token. |
| 400 | currency_not_available | The project cannot accept this currency on any chain. |
| 400 | deposits_disabled | The project has turned deposit addresses off. |
| 400 | amount_below_minimum | Below the minimum amount, given in details.min_amount. |
| 401 | unauthorized | The API key is missing, invalid or revoked. |
| 403 | project_disabled | The project is disabled. |
| 404 | not_found | The resource does not exist or belongs to another project. |
| 409 | request_in_progress | A request with the same Idempotency-Key is still running. Retry shortly. |
| 422 | idempotency_key_reused | The same Idempotency-Key was used with a different request. |
| 500 | internal_error | Server error. Retry later with the same Idempotency-Key. |
Payment intents
A payment intent is an order for the user to pay. The user pays on the checkout page and you get the result by webhook.
Create a payment intent
POST/v1/payment_intents| Parameter | Description |
|---|---|
currency required | Currency, such as USDT. See currencies in GET /v1/chains. |
amount required | Token amount with up to 6 decimal places, such as "25.00". |
chains | Only accept payment on these chains, such as ["bsc", "base"]. By default, every chain where the project accepts this currency. |
customer | The user's ID in your system: 1 to 128 letters, digits or _ - . : @. |
expires_in | Lifetime in seconds, 60 to 604800 (7 days). Default 1800 (30 minutes). |
metadata | Any JSON object, up to 50 keys and 8KB, returned unchanged by the API and webhooks. A good place for your order number. |
success_url | The https URL the checkout returns to after payment. |
cancel_url | The https URL the checkout returns to when the user clicks Cancel. |
Chains where the amount is below the minimum are left out; if none remain, the request fails. The default minimum is 5 USD; your fees are in the Fees section of the project in the dashboard.
Set the token and amount per chain
To accept several currencies, or a different amount per chain, send options instead of currency, amount and chains. Up to 16 items; token is a symbol or contract address.
"options": [
{ "chain": "bsc", "token": "USDT", "amount": "25.00" },
{ "chain": "bsc", "token": "USDC", "amount": "25.00" }
]Response
Returns 201 and the payment intent. Open checkout_url for the user.
{
"id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
"object": "payment_intent",
"status": "pending",
"livemode": true,
"customer": "user_42",
"checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
"metadata": { "order_id": "10086" },
"success_url": "https://your-shop.com/orders/10086",
"cancel_url": null,
"created_at": "2026-11-02T08:30:00Z",
"expires_at": "2026-11-02T09:00:00Z",
"paid_at": null,
"paid_option": null,
"options": [
{
"id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
"chain": "bsc",
"token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
"amount": "25.00",
"received": "0.00",
"deposit_address": "0x8b1F…c04E"
},
{
"id": "pio_2Mn7Xc4bQe6uJs1Ga8RvK3",
"chain": "base",
"token": { "symbol": "USDT", "address": "0xfde4…9bb2", "decimals": 6 },
"amount": "25.00",
"received": "0.00",
"deposit_address": null
}
],
"deposits": []
}| Field | Description |
|---|---|
options | What the user can choose from: one token on one chain per item. |
options[].received | Amount received for this item so far. |
options[].deposit_address | The dedicated transfer address for this payment intent, which you can also show on your own page. null when that method is not available (chains other than BNB Chain, or a very small amount). |
paid_option | The options[].id the user actually paid. |
deposits | Every deposit credited to this payment intent, oldest first. See the deposit object. |
livemode | true on mainnet, false on the testnet. |
Retrieve a payment intent
GET/v1/payment_intents/{id}Returns the payment intent. Use it for reconciliation, or to check the status when a webhook has not arrived.
Payment intent status
| status | Description |
|---|---|
pending | Waiting for payment. |
partially_paid | Transfers to the dedicated address fall short by amount − received. Do not ship; it becomes paid once the user pays the rest. |
paid | Paid in full, ready to ship. Any overpayment also counts in received; kokiwa does not return it. |
expired | Expired without payment. |
paid_late | Funds reached the dedicated address after expiry. The money is yours: decide whether to ship or refund. |
Deposit addresses
Get a customer's deposit address
POST/v1/deposit_addresses| Parameter | Description |
|---|---|
customer required | The user's ID in your system, same rules as payment intents. The user is created on first use. |
chain | An EVM chain: bsc, ethereum, arbitrum, base, polygon, optimism. Default bsc. A customer has the same address on every EVM chain. |
{
"object": "deposit_address",
"customer": "user_42",
"chain": "bsc",
"address": "0x3c9A…71d2",
"tokens": [
{ "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
]
}The same user always gets the same address, so you can show it long term. Only the tokens in tokens are credited.
Every transfer sends deposit.confirmed. Transfers below min_settle_amount are credited too, with status held; once the address has accumulated the minimum, they are swept to your payout address together for one fixed fee.
Deposits
A deposit is one credited on-chain payment, from a payment intent or a deposit address. A payment intent can have several.
{
"id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4",
"object": "deposit",
"status": "settled",
"method": "wallet",
"chain": "bsc",
"customer": "user_42",
"payment_intent": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
"token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
"amount": "25.00",
"fee": "0.0875",
"net": "24.9125",
"usd_value": "25.00",
"confirmed_at": "2026-11-02T08:41:07Z",
"transaction": {
"hash": "0x4e7a…91c3",
"log_index": 212,
"block_number": 44718235,
"block_time": "2026-11-02T08:40:58Z",
"from": "0x1f9C…a2B0",
"to": "0x7d3E…09f1",
"raw_amount": "25000000000000000000"
},
"settlement": {
"tx_hash": "0x4e7a…91c3",
"by": "payment",
"settled_at": "2026-11-02T08:40:58Z"
}
}| Field | Description |
|---|---|
method | wallet: paid from a wallet. deposit_address: transferred to an address. |
customer | The user ID you sent, or null. |
payment_intent | The payment intent it belongs to; null for deposit addresses. |
amount、fee、net | What the user paid, the fee, and what you receive. While held, fee is 0 and is set at sweeping. |
usd_value | amount in US dollars at the token price set by kokiwa. |
transaction | The user's payment on-chain, which you can check on a block explorer. When a transaction has several transfers, hash + log_index identify one. from is not always the user's own wallet: after an exchange withdrawal it is the exchange's address. raw_amount is the raw on-chain value of the transfer in the token's smallest unit, only for checking against a block explorer. |
settlement | The transaction that reached your payout address, or null until settled. by is payment (settled by the payment itself), kokiwa (swept by kokiwa) or owner (reclaimed with your own wallet, no fee). Deposits swept together share a tx_hash. |
| status | Description |
|---|---|
confirmed | Confirmed on-chain, waiting to be swept to your payout address. You can credit the user. |
held | Confirmed on-chain, too small to sweep yet. You can credit the user. |
settled | Reached your payout address. |
Retrieve a deposit
GET/v1/deposits/{id}List deposits
GET/v1/depositsNewest first.
| Query parameter | Description |
|---|---|
customer | Only this user. |
tx_hash | Find by the hash of the payment or settlement transaction. |
limit | Page size, 1 to 100. Default 20. |
starting_after | The id of the last item on the previous page. |
curl "https://api.kokiwa.com/v1/deposits?tx_hash=0x4e7a…91c3" \
-H "Authorization: Bearer $KOKIWA_KEY"
{ "object": "list", "data": [ { "id": "dep_9Kx2…", "object": "deposit", ... } ], "has_more": false }Chains and tokens
kokiwa supports the chains and currencies below. Use the chain column for chains and options[].chain, and the currency column for currency.
chain | Blockchain | Currencies | Payment methods |
|---|---|---|---|
bsc | BNB Chain | USDT, USDC | wallet, deposit_address |
ethereum | Ethereum | USDT, USDC | wallet, deposit_address |
arbitrum | Arbitrum | USDT, USDC | wallet, deposit_address |
base | Base | USDT, USDC | wallet, deposit_address |
polygon | Polygon | USDT, USDC | wallet, deposit_address |
optimism | Optimism | USDT, USDC | wallet, deposit_address |
ton | TON | USDT | wallet |
solana | Solana | USDT, USDC | wallet |
Testnet takes USDT only. The token is tUSDT, but currency is still USDT.
This is the full range of values, not what a given project can accept. Each merchant's setup differs, so check what is available with the endpoint below.
List the project's chains and tokens
GET/v1/chainsReturns what the key's project can accept on the current network.
{
"object": "list",
"livemode": true,
"currencies": ["USDT"],
"data": [
{
"object": "chain", "chain": "bsc", "name": "BNB Smart Chain", "chain_id": 56, "testnet": false, "native": "BNB",
"payout_registered": true, "active": true,
"methods": { "wallet": true, "deposit_address": true },
"tokens": [
{ "symbol": "USDT", "asset": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "decimals": 18, "accepted": true },
{ "symbol": "USDC", "asset": "USDC", "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "decimals": 18, "accepted": false }
]
}
]
}| Field | Description |
|---|---|
currencies | Currencies you can send as currency right now. |
data[].chain | The value for chain and options[].chain: bsc, ethereum, arbitrum, base, polygon, optimism, ton, solana. |
data[].active | Whether the chain can take payments now: payout registered, a payment method on, and a token selected. |
data[].tokens[].asset | The token's currency. Tokens with the same asset are equivalent across chains. |
data[].tokens[].accepted | Whether the project selected this token. |
Customers
Optional. A customer is created the first time a customer value appears; you only need these endpoints to filter by tag in the dashboard.
Set a customer's label and note
PUT/v1/customers/{external_id}| Parameter | Description |
|---|---|
tags | Up to 20 tags of 1 to 64 letters, digits or _ - . :. |
metadata | Any JSON object, up to 50 keys and 8KB. |
Retrieve a customer
GET/v1/customers/{external_id}Returns the tags, notes and deposit_addresses (deposit addresses by chain).