Overview
The Merchant API lets your server create crypto deposits and withdrawals. Your customer pays on our hosted checkout page; you learn about every change through signed webhooks and can always read the current state back from the API. Every status, event and wait is drawn step by step under Lifecycle.
Base URL
| Environment | Base URL | API keys |
|---|---|---|
| Production | https://api.cryptogon.dev | live_… |
| Sandbox (test networks, no real money) | https://api-sandbox.cryptogon.dev | test_… |
Networks and assets
| Network | Production code | Assets | Sandbox code | Sandbox assets |
|---|---|---|---|---|
| TRON | tron | USDT, TRX | tron_nile | USDT, TRX |
| BNB Smart Chain | bsc | USDT, USDC, BNB | bsc_testnet | BNB |
| Ethereum | ethereum | USDT, USDC, ETH | ethereum_sepolia | USDC, ETH |
Which assets are open depends on the environment and on your contract. GET /v1/assets returns the live list with network codes, decimals and contract addresses: build your menus from it instead of hard-coding them.
Deposit flow (recommended: payment session)
- Your server opens a payment session with
POST /v1/deposit-sessions: the amount, the currency (TRY,EUR,USDT…) and your own order reference. - Redirect the customer to the returned
checkout_url. They choose the coin and network there; the page shows the exact amount, the address and a QR code. - The customer sends the payment. We watch the chain and wait until the transfer is final.
- You receive
payment.detectedand thenpayment.confirmedwebhooks. Answer each with2xx. - Credit your customer with the payment’s
order_value.value(see the crediting rules under Webhooks). Your Cryptogon balance grows by the net amount after commission once your server has answeredpayment.confirmedwith2xx.
If you want to choose the coin and network yourself, use POST /v1/deposits instead: it works the same way, with a fixed asset, and sends deposit.* events.
Withdrawal flow
- Optional:
POST /v1/withdrawals/quoteshows the network fee and the minimum the customer will receive. POST /v1/withdrawalswith the destination address and amount. The answer is201withstatus: processing. If your balance is short, the withdrawal waits for balance for up to 12 minutes (default) and still showsprocessing.- Approval: within your auto-approval limit and with no hold, it is approved automatically. Otherwise it becomes
pending_approval(withdrawal.pending_approval) and waits for you or for Cryptogon. See Approval. - We sign and broadcast it:
withdrawal.sentwithtx_hash. withdrawal.completedwhen it is final on chain. If it is rejected, cancelled or fails, you getwithdrawal.rejected,withdrawal.cancelledorwithdrawal.failedand the locked amount returns to your balance.
Your Cryptogon balance
- Deposits: a final deposit is first recorded as pending. Its net amount (gross minus
commission.amount) becomes available once your webhook URL has answered the confirming event (deposit.confirmedorpayment.confirmed) with2xx; we check every minute.commission.credited_atshows when. Without a webhook URL the credit waits. - Withdrawals: the amount, our withdrawal fee and a network-fee ceiling are locked when the withdrawal is accepted (on TRON: the amount and the withdrawal fee). The real network fee is charged after sending and the rest is released. A rejected, cancelled or failed withdrawal releases its lock.
- Top-ups (
site.funded) and credit from Cryptogon (credit.approved) increase the available balance directly, without commission. - There is no balance endpoint yet; the merchant panel shows the balance.
Statuses
| Payment session | Meaning |
|---|---|
awaiting_selection | The customer has not chosen a coin and network yet |
awaiting_payment | Chosen; waiting for the payment |
detected | A payment is on chain but not final |
confirmed | The payment is final; credit it (crediting rules under Webhooks) |
expired | Time ran out and no payment arrived |
| Deposit request | Meaning |
|---|---|
pending | Waiting for the payment |
detected | The transfer is on chain but not final |
confirmed | Final; transfer.variance tells you exact, under or over |
expired | Time ran out and no payment arrived |
| Withdrawal | Meaning |
|---|---|
processing | Accepted and on its way: also while it waits for balance, after approval and while it is being signed |
pending_approval | Waiting for a decision: yours (above your auto-approval limit or one of your rules) or Cryptogon’s (no rate, stablecoin off its peg, site not active, blocklisted address, or no approver on your site) |
sent | Broadcast; tx_hash is set (on a split withdrawal: in parts) |
completed | Final on chain |
partially_completed | Split withdrawal whose destination was blocked during the withdrawal because of fraud or sanctions: paid_amount was paid, the rest is back in your balance. Final. The only case where a split withdrawal does not end at the full amount |
rejected | Rejected before sending; the lock is released (rejection_reason says why for withdrawals rejected while waiting for balance) |
cancelled | Cancelled by you before signing |
failed | Could not be sent, or failed on chain; the lock is released (a network fee already spent on chain is charged) |
Ground rules
- Amounts are decimal strings:
"100.5", never the JSON number100.5. - Every request that moves money carries an
Idempotency-Key; retrying with the same key and body is always safe. merchant_referenceis your own transaction ID: 1–100 characters of letters, digits and_ . : -, unique per site.player_idis your ID for the customer: 1–64 characters of the same set.- Request bodies are JSON objects. Unknown fields are refused with
400 INVALID_REQUEST, so a typo never passes silently. - Webhooks can arrive more than once and out of order. Process each event once by its
idand trustdata.status, not the event type. - v1 may add fields, statuses and event types but never changes the meaning of existing ones: ignore what you do not recognise (an unknown status is not final). Dated changes are listed under Changelog.
Not available yet
GET /v1/balances, POST /v1/settlements and an OpenAPI schema come in later versions. Credit requests and top-up addresses are in the merchant panel, not in this API.
Lifecycle
Each diagram shows what your server sees at each step: the status the API returns, the webhook we send (or none) and what you do. Internal steps (waiting for balance, signing) are never shown separately: the API keeps answering processing. Every diagram has a table with the same content below it.
- Wait
- Credit
- Give back
- Nothing to do
- Done
On a narrow screen, scroll a diagram sideways inside its frame. “Give back” means: return the amount to your customer in your own system.
Deposits
The boxes show the payment session (POST /v1/deposit-sessions). The table also gives the deposit request (POST /v1/deposits) for every step; a request has no choice step and no extra payments.
| Step | status | Webhook | Deposit request | When | What you do |
|---|---|---|---|---|---|
| Session opened | awaiting_selection | no event | pending · no event | The session exists; the customer has not chosen a coin and network yet. A deposit request (POST /v1/deposits) starts directly at waiting for payment (pending). | Wait Send the customer to checkout_url. |
| Coin and network chosen | awaiting_payment | no event | n/a | The checkout page shows the amount, address and QR code; the rate is locked for 15 minutes. The customer may switch up to 8 times. | Wait Wait. |
| Seen on chain | detected | payment.detected | detected · deposit.detected | A transfer is on chain but not final yet. | Wait Show it as pending to the customer; do not credit yet. |
| Final | confirmed | payment.confirmed | confirmed · deposit.confirmed | The transfer is final. Your balance is credited with the net amount after you answer the event with 2xx. | Credit Credit order_value.value once by payment id (request: transfer.amount once by request id). |
| Expired | expired | payment.expired | expired · deposit.expired | Time ran out with no transfer seen: the choice window and every chosen address (request: expires_at). | Nothing to do Nothing to credit. |
| Dropped before final | awaiting_payment | payment.dropped | pending · deposit.dropped | A seen transfer disappeared from the chain. The session or request stays open for a new transfer. | Wait Do not credit. |
| Extra or late payment | confirmed | payment.extra | n/a | A second payment, or a late payment tied to this session; held. The session keeps its status. | Nothing to do Do not credit it while credit_status is held. |
| Released after review | confirmed | payment.released | n/a | Cryptogon reviewed a held payment and released it (credit_status: pending). | Credit Credit it once by payment id, even if the session expired or was already credited. |
- One open request per customer and asset. A new deposit request in the same asset gets
409 OPEN_DEPOSIT_EXISTSwhile another request or a session’s chosen address in that asset is open. Exception: a deposit request whose payment window (pay_until) has passed with no transfer seen is closed asexpired(deposit.expired) and the new one opens. In a session, an asset the customer already has an open request in cannot be chosen until that request closes. - Expiry. A deposit request lives 300–1800 seconds (
expires_in; default 900 for native coins, 1800 for stablecoins). A session gives the customer 300–1800 seconds to choose (default 1800), then each chosen address has its own payment time (15 minutes in a fiat session). A transfer that is already seen when time runs out keeps the request open until it is final or dropped. - Underpayment and overpayment. There is no tolerance: credit what arrived. In a session
order_value.valueis the received amount in the session currency, rounded down; in a deposit requesttransfer.amountis the received amount andtransfer.variancesaysexact,underorover. - Late payments. A payment after the choice expired, in the wrong coin or on a sibling EVM network is tied to the customer’s only session that showed an address on that chain and is open or closed in the last 24 hours. It arrives held (
late_payment) withpayment.extraand is valued at the rate when it became final (confirm_rate). If it cannot be tied to exactly one session, it is handled like a payment without a request. - Payments without a request. A transfer to a customer’s permanent address with no open deposit request and no session it can be tied to (also a second transfer to a request that already has one) is recorded but sends no event and does not reach your available balance. Our team reviews it. Transfers below the asset’s minimum deposit are not tied to a session. There is no automatic crediting of such payments in v1.
- Pauses. If Cryptogon pauses address issuing, new deposit requests, sessions and customer addresses get
503 SERVICE_PAUSEDandaddressisnull; payments to addresses already shown are still detected and confirmed. If Cryptogon pauses crediting, or a stablecoin drifts off its peg, events are still sent but the credit to your balance waits until the pause ends. A stablecoin off its peg also refuses new deposit requests in that asset (503 ASSET_PAUSED).
Withdrawals
| Step | status | Webhook | When | What you do |
|---|---|---|---|---|
| Waiting for balance | processing | no event | Your available balance does not cover amount and fees, or an earlier withdrawal in the same asset is still waiting. Nothing is locked; fees is null. | Wait Top up if you want it paid; you may cancel. |
| Accepted, balance locked | processing | no event | Amount and fees are locked; your limits and Cryptogon’s checks run. | Wait Wait for the next event. |
| Waiting for approval | pending_approval | withdrawal.pending_approval | Held by your limits or by Cryptogon’s checks. After approval the status returns to processing until it is sent. | Wait Decide in the merchant panel if it waits for you. |
| Sent to the network | sent | withdrawal.sent | tx_hash is set. It can no longer be cancelled. | Wait Wait for the result. |
| Completed | completed | withdrawal.completed | Final on chain. | Done Mark the payout as paid. |
| Balance wait ended | rejected | withdrawal.rejected | The window ended without enough balance, or a person rejected it while it waited. rejection_reason says why. | Give back Return the amount to your customer. Nothing was locked. |
| Cancelled by you | cancelled | withdrawal.cancelled | Cancelled before signing started (also while waiting for balance or approval). | Give back Return the amount to your customer. |
| Rejected | rejected | withdrawal.rejected | By one of your rules, by you, after 72 hours without a decision, or by Cryptogon before sending. | Give back Return the amount to your customer. The lock is released. |
| Failed | failed | withdrawal.failed | Could not be sent, or failed on chain. The lock is released; a network fee already spent is charged. | Give back Return the amount to your customer. |
- Cancelling.
POST /v1/withdrawals/{id}/cancelworks while the withdrawal waits for balance, is accepted, waits for approval or is approved but not yet being signed; a split withdrawal also while Cryptogon has paused it and none of its parts has been signed. After signing has started, or once it is final, the answer is409 INVALID_STATE. - Rejected after approval. Until it is signed, Cryptogon can still reject an approved withdrawal (for example when the destination was blocklisted after approval). It goes from
processingtorejectedand the full amount returns to your balance. - Very large withdrawals. A withdrawal above the per-transaction limit may be approved and paid by Cryptogon in several on-chain transactions (see "Split withdrawals" below). You still see one withdrawal. No part is sent until Cryptogon has reserved on-chain liquidity for the whole amount; until then it stays
processing, which can take a while for a large amount.withdrawal.sentcomes once, at the first part, and a single final event ends it;fees.network_feeis the sum of the parts. If Cryptogon pauses it, the remaining parts wait and the withdrawal staysprocessing(sentonce a part went out), with no event; when sending resumes it completes at the full amount (withdrawal.completed). A split withdrawal always ends at the full amount. The only exception: if the destination address is blocked during the withdrawal because of fraud or sanctions, the rest is not sent:partially_completed(withdrawal.partially_completed), orfailedif nothing was paid yet, and the unpaid rest returns to your balance. Before any part is signed Cryptogon can still reject it (failed). - Pauses. If Cryptogon pauses sending, withdrawals are still accepted and approved; they wait in
processingand are sent in order when sending resumes.
Approval
Every accepted withdrawal goes through your limits first, then through Cryptogon’s checks. Cryptogon does not judge your customers and, since 18 October 2026, applies no amount limit of its own: your auto-approval limit decides which withdrawals wait for you.
| Step | status | Webhook | When | What you do |
|---|---|---|---|---|
| Accepted and checked | processing | no event | Right after acceptance (or after the balance wait) your limits run, then Cryptogon’s checks; usually within a minute. | Wait Wait for the next event. |
| Waiting for you | pending_approval | withdrawal.pending_approval | At or above your auto-approval limit (or the USD value is unknown), or one of your hold rules applies. Skipped if your site has no user who may approve withdrawals: it waits for Cryptogon instead. | Wait Approve or decline in the merchant panel within 72 hours. Cryptogon can also decide on your behalf. |
| Waiting for Cryptogon | pending_approval | withdrawal.pending_approval | No current rate, stablecoin off its peg, site or account not active, blocklisted destination, or your hold with no approver on your site. Coming from your review, the event is sent again. | Wait Wait; one authorised person at Cryptogon decides. |
| Approved | processing | no event | No hold, or approved. Next: sending (withdrawal.sent). | Wait Wait for withdrawal.sent. |
| Rejected by your rule | rejected | withdrawal.rejected | Above your per-withdrawal maximum, or a per-customer limit set to reject. | Give back Return the amount to your customer (rejection_reason: null). |
| Declined or timed out | rejected | withdrawal.rejected | You (or Cryptogon on your behalf) declined, nobody decided within 72 hours, or Cryptogon declined it for its own risk. | Give back Return the amount to your customer. |
| Declined by Cryptogon | rejected | withdrawal.rejected | Cryptogon declined a withdrawal it held. | Give back Return the amount to your customer. |
| Rule | Set by | Result |
|---|---|---|
| Auto-approval limit: the USD value is at or above it, or the value is unknown | You, in the merchant panel (Limits); at most 5,000 USD there, default 5,000 USD. Cryptogon can set a higher limit or turn it off | Waits for you (pending_approval) |
| Per-withdrawal maximum | You | Rejected at once (withdrawal.rejected); waits for you if the USD value is unknown |
| Per-customer daily amount, daily count, hourly count | You (off by default) | Waits for you or is rejected, as you choose |
| First withdrawal, new address, a deposit in the last N minutes | You (off by default) | Waits for you |
| No user on your site may approve withdrawals | — | Your holds wait for Cryptogon instead of you |
| No current rate, stablecoin off its peg, site or account not active, destination on Cryptogon’s blocklist | Cryptogon | Waits for Cryptogon. A blocklisted destination cannot be approved; an inactive site’s approved withdrawal is not sent until the site is active again |
| No decision from you within 72 hours | — | Rejected (withdrawal.rejected) |
| None of the above | — | Approved automatically |
- You decide in the merchant panel (Withdrawals), with two-step verification; one approval is final. When you approve, Cryptogon’s checks run again: the withdrawal is approved, or it moves to Cryptogon and
withdrawal.pending_approvalis sent again with a higherresource_version. - Cryptogon can approve or decline a withdrawal that waits for you on your behalf, and can decline it for its own risk reasons. Rejections that do not come from the balance wait have
rejection_reason: null. - Raising your limit does not approve withdrawals that are already waiting.
Waiting for balance
| Time | Step | status | Webhook | What you do |
|---|---|---|---|---|
| 0 | Request accepted 201 with processing and fees: null; no event. | processing | no event | Wait Wait. |
| every minute | Balance checks In request order per asset; a later request never overtakes an earlier one. | processing | no event | Wait Top up if you want it paid. |
| when your balance is enough | Balance arrives The amount is locked and fees are fixed; it continues like any accepted withdrawal. | processing | no event | Wait Wait for the next event. |
| any time while it waits | You cancel POST /v1/withdrawals/{id}/cancel. | cancelled | withdrawal.cancelled | Give back Return the amount to your customer. |
| while it waits | Declined by a person rejection_reason: declined (Cryptogon or a user of your panel; also a TRON withdrawal that no longer meets the minimum). | rejected | withdrawal.rejected | Give back Return the amount to your customer. |
| after 12 minutes, usually within one more | Window ends rejection_reason: insufficient_funds, rate_unavailable, service_unavailable or internal_error. Never paid afterwards. | rejected | withdrawal.rejected | Give back Return the amount to your customer. |
- A withdrawal waits when your available balance does not cover the amount and fees, or when an earlier withdrawal in the same asset is still waiting (requests are served in order). Nothing is locked while it waits, and
feesisnull. - The window is 12 minutes by default; Cryptogon sets it per site (0 turns waiting off, and then a short balance is refused at once with
422 INSUFFICIENT_NETWORK_BALANCE). rejection_reasonafter the window:insufficient_funds(the last check saw too little balance and it is still too little),rate_unavailable(no current rate for the withdrawal fee),service_unavailable(your site or the asset was not active, or the wait could not be processed in time; for example your balance was enough when the window ended) orinternal_error. A withdrawal rejected this way is never paid.rejection_reason: declined: a person rejected it while it waited (Cryptogon, or a user of your merchant panel), or a TRON withdrawal no longer met the minimum amount when the balance arrived.
Authentication
API keys
Create keys in the merchant panel under API and webhook (two-step verification). A site can have up to 10 open keys. Each key has two parts:
- Key ID (
live_ortest_followed by 30 letters and digits, 35 characters): sent openly with every request. Production accepts onlylive_keys, the sandbox onlytest_keys. - Secret (43 characters): never sent, only used to sign. It is shown once; we store it encrypted and cannot show it again. If it leaks, close the key at once and create a new one.
| Scope | Allows |
|---|---|
read | Reading deposit requests, payment sessions, withdrawals and currencies; withdrawal quotes |
deposit | Opening deposit requests and payment sessions, customer addresses; reading deposit requests, sessions and currencies |
withdraw | Opening and cancelling withdrawals, reading them; withdrawal quotes |
settlement | Reserved for settlements (not available yet) |
| any scope | GET /v1/assets and GET /v1/rates |
Allowed server addresses
You can limit a key to a list of server addresses; requests from any other address get 403 IP_NOT_ALLOWED. The list is optional: without it the key works from anywhere. We strongly recommend a list for every key with the withdraw scope.
- Entries are single addresses or ranges in CIDR notation; version 4 and version 6 addresses are compared only with entries of their own kind.
- Keys created in the merchant panel take up to 20 entries; a version 4 range may be no wider than /16, a version 6 range no wider than /48.
- A key’s scopes and address list never change after creation: to change them, create a new key and close the old one.
Rotating and closing keys
When you close a key in the merchant panel, choose how:
- Close now (the choice for a leaked key): the key stops working at once.
- Close after N days (N is 1–7, the panel suggests 7): the old key keeps working normally until then, so you can move your servers to a new key. The closing time is shown next to the key and cannot be moved or undone, but you can still close the key at once.
- A key in its overlap period counts towards the 10-key limit. A closed key, whichever way it was closed, gets
401 UNAUTHORIZEDlike any invalid key. - If a key closes between our signature check and the end of your request, the request gets
401 UNAUTHORIZEDand nothing is written; retry with the new key.
Signing a request
Every request carries three headers:
| Header | Value |
|---|---|
X-Cryptogon-Key | Your key ID |
X-Cryptogon-Timestamp | Unix time in whole seconds; at most 5 minutes away from our clock |
X-Cryptogon-Signature | v1= + the lower-case hex HMAC-SHA256 of the signing text, keyed with your secret |
The signing text is four lines joined with \n (newline). The HMAC key is the 43-character secret itself, as text.
<timestamp>
<METHOD>
<path including the query string, exactly as sent>
<hex SHA-256 of the request body (of the empty string when there is no body)>X-Cryptogon-Key: test_8f2aC71d0b5e4c39a6f1d2e7b8c90a1b4
X-Cryptogon-Timestamp: 1791975600
X-Cryptogon-Signature: v1=5f0c6b1e9a…
Idempotency-Key: order-1001
Content-Type: application/json- Sign the exact bytes you send. Do not re-format the JSON after signing.
- Requests with a body need
Content-Type: application/json(otherwise415); the body may be at most 64 KB (otherwise413). - The path includes the query string exactly as sent:
/v1/deposits?merchant_reference=order-1001. - Any key, timestamp or signature problem gets the same answer:
401 UNAUTHORIZED. That includes a missing header, a key ID in the wrong format, a key of the other environment and a closed key.
Order of checks
- Host name:
421 MISDIRECTED_REQUEST. - Requests per client address (before the signature is checked):
429 RATE_LIMITED. - Body type and size:
415or413, both with codeINVALID_REQUEST. - Headers, key and signature:
401 UNAUTHORIZED. - Your site is active:
403 SITE_NOT_ACTIVE. - The key has the scope:
403 INSUFFICIENT_SCOPE. - The request comes from an allowed address:
403 IP_NOT_ALLOWED. - The body is a JSON object:
400 INVALID_REQUEST. - Requests per site:
429 RATE_LIMITED. - Fields,
Idempotency-Keyand business rules: the codes under Errors.
Idempotency
POST /v1/deposits, POST /v1/deposit-sessions, POST /v1/withdrawals and POST /v1/withdrawals/{id}/cancel require an Idempotency-Key header: 8–100 characters of letters, digits and _ . : -.
- The key is matched with the method, the path (without the query string) and the exact body bytes. The same key with the same request returns the record in its current state: the first answer is
201(cancel:200), repeats are200. - The same key with a different request:
422 IDEMPOTENCY_KEY_REUSED. If the request fails, the key is not kept and can be used again. - The real uniqueness is
merchant_reference. The same reference with the same content under a new key also returns the existing record with200, even when two requests arrive at the same moment. The same reference with different content is409 DUPLICATE_REFERENCE. Deposit requests and payment sessions share one reference space; withdrawals have their own. - Content that must match: deposit request:
player_id,network,asset,amount; session:player_id,currency,amount,options; withdrawal:player_id,network,asset,address(after checksum normalisation),amount.expires_inis not compared. - On a timeout, retry with the same key and the same body. Keys are kept for 7 days.
Amounts
- Amounts always travel as decimal strings:
"100.5". A JSON number is rejected because it is floating point. Zero is rejected. - A crypto amount may not have more decimals than the asset (
decimalsinGET /v1/assets). - Fiat amounts follow the currency’s minor units (
minor_unitsinGET /v1/currencies):"500.00"TRY,"5000"JPY. Trailing zeros are fine ("500.00"JPY is 500); extra decimals are rejected, not rounded.
Rate limits
| Limit | Per minute | Counts |
|---|---|---|
| Per client address | 1,800 | Every request, before the signature is checked. Version 6 addresses count per /64 network |
| Per site | 1,200 | Every signed request of your site |
| Per site, creating | 300 | POST /v1/deposits, POST /v1/deposit-sessions and POST /v1/players/{player_id}/addresses (also counted in the site limit) |
Short bursts are allowed: each limit refills continuously. Above a limit you get 429 RATE_LIMITED with a Retry-After header in seconds; wait that long and retry with the same Idempotency-Key.
Endpoints
All paths are relative to the base URL. Records of another site, records that do not exist and IDs that are not UUIDs all answer 404 NOT_FOUND. Lookups by merchant_reference need the query parameter (otherwise 400).
GET/v1/assets
The assets open in this environment.
{
"data": [
{
"network": "tron",
"asset": "USDT",
"name": "Tether USD",
"decimals": 6,
"contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"family": "tron",
"chain_id": null
}
]
}GET/v1/rates
Current USD value of each open asset: the median of at least three exchanges, refreshed every minute.
{
"data": [
{ "asset": "ETH", "usd": "2687.765", "pegged": false, "available": true, "updated_at": "2026-10-04T10:00:00.000Z" },
{ "asset": "USDT", "usd": "1", "pegged": true, "market_usd": "0.999825", "available": true, "updated_at": "2026-10-04T10:00:00.000Z" }
]
}- Stablecoins (
pegged) count as 1 USD;market_usdis the exchange price. If it drifts 1% or more from 1 USD,availablebecomesfalseand new deposits in that asset get503 ASSET_PAUSED. - If a native coin (ETH, BNB, TRX) has no reliable rate,
usdisnulland new requests get503 RATE_UNAVAILABLE.
GET/v1/currencies
The fiat currencies your site accepts for payment sessions.
{
"data": [
{ "code": "TRY", "minor_units": 2, "available": true, "per_usd": "41.18", "updated_at": "2026-10-05T12:00:00.000Z", "max_amount": "100000.00" },
{ "code": "USD", "minor_units": 2, "available": true, "per_usd": "1", "updated_at": null, "max_amount": null }
]
}With available: false no session can be opened right now (no rate, or not enabled); per_usd is only returned while the currency is enabled. max_amount is your per-session limit in that currency (null: none).
POST/v1/deposit-sessions
Open a payment session: you send the amount and currency, the customer picks the coin and network on the checkout page.
{
"merchant_reference": "order-7781234",
"player_id": "customer-42",
"amount": "500.00",
"currency": "TRY",
"options": [
{ "network": "tron", "asset": "USDT" },
{ "network": "bsc", "asset": "USDT" }
],
"expires_in": 1800
}| Field | Rule |
|---|---|
merchant_reference | Required. Your transaction ID, unique per site (shared with deposit requests) |
player_id | Required. Your ID for the customer; the customer’s deposit addresses are permanent per ID |
currency | Required. ISO 4217 code (GET /v1/currencies) or an open crypto symbol such as USDT (then only that coin is offered and nothing is converted). Not enabled for your site: 422 CURRENCY_NOT_SUPPORTED |
amount | Optional decimal string. Without it the customer sends any amount. Above your limit: 422 AMOUNT_OUT_OF_RANGE |
options | Optional, 1–50 items of exactly { "network", "asset" }. Only these are offered; otherwise everything your site accepts. A repeated or unknown item: 400; not open for your site or environment: 422 ASSET_NOT_AVAILABLE |
expires_in | Seconds the customer has to choose: 300–1800, default 1800 |
{
"id": "6f1c2a7e-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
"merchant_reference": "order-7781234",
"player_id": "customer-42",
"status": "awaiting_selection",
"amount": { "value": "500.00", "currency": "TRY" },
"checkout_url": "https://cryptogon.app/p/b7mLw80n-qQJCa1eOqefaNH-Hzad0RoCNBYqA7poDVc",
"choose_until": "2026-10-05T12:30:00.000Z",
"created_at": "2026-10-05T12:00:00.000Z",
"selection": null,
"payment": null,
"extra_payments": []
}After the customer chooses, selection is filled in (and shows the latest choice if they switch network):
"selection": {
"network": "tron",
"asset": "USDT",
"address": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
"crypto_amount": "12.15",
"quote": { "basis": "fx", "fx_per_usd": "41.18", "crypto_usd": "1", "locked_until": "2026-10-05T12:20:00.000Z" },
"pay_until": "2026-10-05T12:19:00.000Z",
"expires_at": "2026-10-05T12:20:00.000Z",
"selections": 2
}- Rate and amount. In a fiat session the rate is locked for 15 minutes when the customer chooses. The crypto amount is rounded up: you never receive less than the order amount, and there is no spread. In a crypto session
basisisidentityand nothing is converted. - Switching. Before paying, the customer can change coin or network up to 8 times (at most 4 different addresses). Earlier addresses keep accepting payments until they expire; if two arrive, only one wins and the other is held in
extra_payments. An asset in which the customer already has an open deposit request cannot be chosen. - Payment window.
pay_until=expires_atminus a network margin (1 minute on TRON and BSC, 3 on Ethereum). The address is shown until then; a transfer seen beforeexpires_atstill counts.addressisnullwhile address issuing is paused, the site is not active, or once another choice has been paid or the session is paid.
payment is the deposit that paid the session (before it is final: the first payment seen); extra_payments has the same shape:
"payment": {
"id": "a1b2c3d4-0000-4000-8000-000000000004",
"network": "tron",
"asset": "USDT",
"tx_hash": "…",
"amount": "12.15",
"status": "confirmed",
"order_value": { "value": "500.00", "currency": "TRY", "basis": "locked" },
"variance": "exact",
"credit_status": "pending",
"hold_reason": null,
"detected_at": "2026-10-05T12:05:00.000Z",
"confirmed_at": "2026-10-05T12:06:00.000Z",
"commission": { "rate": "1.5", "amount": "0.18225", "net": "11.96775", "fixed_at": "2026-10-05T12:06:00.000Z", "credited_at": null }
}order_value: what was received, in the session currency, rounded down. This is what you credit, not the order amount: an underpayment credits less, an overpayment more.nullbefore the payment is final.basisislocked,identity(crypto session),confirm_rate(late payment) orunavailable(no value; the payment is held).credit_status:pending(final, not held),credited(the net amount is in your Cryptogon balance),failed(the confirming event could not be delivered for 24 hours; see Webhooks) orheldwithhold_reason(extra_payment,late_payment,no_valuation). Never creditheld.commission: our deposit commission, taken in the payment’s own coin.order_valuestays gross; your balance grows bynet.
If the currency has no fresh rate: 503 FX_UNAVAILABLE with Retry-After: 60. If nothing can be offered (no assets on your site, or the amount is below every coin’s minimum): 422 NO_PAYMENT_OPTION. A repeat of the same request returns the session in its current state with 200.
GET/v1/deposit-sessions/{id} · /v1/deposit-sessions?merchant_reference=…
Read a payment session by its ID or by your reference. Same shape as above. The session’s choices do not appear under GET /v1/deposits.
POST/v1/deposits
Open a deposit request in an asset you choose.
{
"merchant_reference": "order-1001",
"player_id": "customer-42",
"network": "bsc",
"asset": "USDT",
"amount": "100.5",
"expires_in": 1800
}amountis optional (without it the customer sends any amount).expires_in: 300–1800 seconds; the default is 900 for native coins (the rate-lock time) and 1800 for stablecoins.- The customer’s address is permanent: the same customer and network always get the same address.
- An open request or session address in the same asset:
409 OPEN_DEPOSIT_EXISTS, unless an open request’s payment window has passed with no transfer seen; then it closes asexpiredand the new one opens. - While address issuing is paused, new requests and repeats get
503 SERVICE_PAUSED.
{
"id": "f2f7dc13-a7c5-4869-b319-3802e5df44b4",
"merchant_reference": "order-1001",
"player_id": "customer-42",
"status": "pending",
"network": "bsc",
"asset": "USDT",
"address": "0x8BAE832C68d7c90C11bCA5EB8Bd0f14d49bd9e8F",
"amount": "100.5",
"rate": null,
"expires_at": "2026-10-03T21:47:43.622Z",
"created_at": "2026-10-03T21:17:43.622Z",
"checkout_url": "https://cryptogon.app/p/pRI-j9KWJeCjolfdZJJlUZ1fJHdoiaawqyeljswwBMA",
"transfer": null
}- Rate lock. For native coins the current rate is locked for 15 minutes (
rate.usd,rate.locked_until), never beyond the request’s expiry. Payments without an open request use the rate when they become final. Stablecoins haverate: null(1 USD). - Transfer. Once a transfer is seen,
transfershowstx_hash,amount(received),status,variance,credit_status(pending,credited,failed),detected_at,confirmed_atandcommission. - Commission. When the deposit is final,
transfer.commissionshows our commission in the deposit’s coin; your balance grows bynet.amountstays gross. - Address.
addressisnullon an open request with no transfer while address issuing is paused or the site is not active. After the request closes, the checkout link shows only the status for 24 hours, then answers404.
"commission": {
"rate": "1.5",
"amount": "1.5",
"net": "98.5",
"fixed_at": "2026-10-07T10:06:00.000Z",
"credited_at": null
}GET/v1/deposits/{id} · /v1/deposits?merchant_reference=…
Read a deposit request. Same shape as above.
POST/v1/players/{player_id}/addresses
The customer’s permanent deposit address on one network, for reconciliation. Answers 200; creates the customer if needed.
{ "network": "tron" }{ "player_id": "customer-42", "network": "tron", "address": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7" }A transfer to this address without an open deposit request or session sends no event and is not credited automatically (see Lifecycle). Address not ready yet: 503 ADDRESS_NOT_READY; address issuing paused: 503 SERVICE_PAUSED.
POST/v1/withdrawals/quote
Network fee and the minimum the customer receives, before you open a withdrawal. Answers 200, stores nothing, needs no Idempotency-Key.
{ "network": "tron", "asset": "USDT", "amount": "100" }{
"network": "tron",
"asset": "USDT",
"amount": "100",
"network_fee_payer": "player",
"network_fee_max": "6.12",
"net_min": "93.88",
"parts": 1,
"min_net": "0",
"min_amount": "10"
}network_fee_payer: on TRON (TRC20) the network fee is deducted from the amount the customer receives ("player"); on other networks it is charged to your balance separately ("merchant", andnet_min=amount).network_fee_max: the most the network fee can be for all parts;net_min: the least the customer receives. The real fee is computed just before signing and is usually lower.parts: in how many transactions the amount would be sent.min_amount: the smallest withdrawal on TRON, gross (10 USD worth including the fee; 10 units for USD-pegged assets). Below it, or if a part does not exceed the fee ceiling:422 AMOUNT_TOO_SMALL.min_netis always"0"(kept for older clients).- The quote is not stored: the fee is computed again when the withdrawal is accepted. If it cannot be computed right now:
503 FEE_UNAVAILABLEwithRetry-After.
POST/v1/withdrawals
Send crypto to your customer’s address.
{
"merchant_reference": "payout-5001",
"player_id": "customer-42",
"network": "bsc",
"asset": "USDT",
"address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
"amount": "10"
}{
"id": "0d4b7a6e-1c2f-4e3a-9b8c-7d6e5f4a3b2c",
"merchant_reference": "payout-5001",
"player_id": "customer-42",
"status": "processing",
"network": "bsc",
"asset": "USDT",
"address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
"amount": "10",
"paid_amount": "0",
"tx_hash": null,
"parts": [],
"created_at": "2026-10-11T10:00:00.000Z",
"updated_at": "2026-10-11T10:00:00.000Z",
"fees": {
"withdrawal_fee": "1.5",
"network_fee_max": "3",
"network_fee": "0",
"charged": null,
"released": null,
"state": "held",
"fixed_at": "2026-10-11T10:00:00.000Z",
"closed_at": null,
"network_fee_payer": "merchant",
"player_network_fee_max": null,
"player_network_fee": null,
"net_amount": null
},
"rejection_reason": null
}- The answer is always
processing(201; a repeat200). The approval decision comes afterwards, usually within a minute, as an event: see Approval. - The amount is locked from your site balance when accepted. If your available balance is short, the withdrawal waits for balance instead (below).
- The address is checked against the chain’s format and checksum: otherwise
422 INVALID_ADDRESSwithreason(format,checksumornetwork). Lower-case EVM addresses are accepted and stored in EIP-55 form. Our own deposit addresses and token contracts are refused with422 INVALID_ADDRESSwithoutreason. merchant_referencecannot start withcg:(reserved):400 INVALID_REQUEST.- Response fields:
id,merchant_reference,player_id,status,network,asset,address,amount,tx_hash,created_at,updated_at(last status change),fees,rejection_reason.
- Fees. Our withdrawal fee and the network fee are not deducted from what the customer receives: they are charged to your balance in the withdrawn asset. A network-fee ceiling is held at acceptance; the real fee is charged after sending (part by part for a split withdrawal) and the rest is released when the withdrawal closes. If it fails on chain, the withdrawal fee is not charged but the network fee spent is.
- TRON (TRC20): the customer pays the network fee. It is deducted from the amount (
net_amount=amount−player_network_fee) and never exceeds the ceiling fixed at acceptance (player_network_fee_max). If the fee cannot be computed, the withdrawal is not opened (503 FEE_UNAVAILABLE). If it fails on chain after sending,amount−player_network_feereturns to your balance.
"fees": {
"withdrawal_fee": "1.5",
"network_fee_max": "0",
"network_fee": "0",
"charged": null,
"released": null,
"state": "held",
"fixed_at": "2026-10-11T10:00:00.000Z",
"closed_at": null,
"network_fee_payer": "player",
"player_network_fee_max": "6.12",
"player_network_fee": "3.01",
"net_amount": "96.99"
}GET/v1/withdrawals/{id} · /v1/withdrawals?merchant_reference=…
Read a withdrawal. Same shape as above.
Split withdrawals. A withdrawal above our per-transaction signing limit may be sent in several parts. parts lists them in order (amount, status, tx_hash); for a normal withdrawal it is empty. The top-level tx_hash stays null: see parts. paid_amount is the gross amount paid out, in the same terms as amount (before the customer’s network fee; for the net amount see fees.net_amount); on a normal withdrawal it is amount once completed, otherwise "0". withdrawal.sent comes once, when the first part is broadcast; the withdrawal ends with exactly one of withdrawal.completed, withdrawal.partially_completed, withdrawal.failed or withdrawal.cancelled. Before the first part, Cryptogon reserves on-chain liquidity for the full amount; while it waits for that reservation the withdrawal is processing, every part is processing with tx_hash: null, and you can still cancel it. If Cryptogon pauses a split withdrawal, the unsent parts stay processing, the reservation is kept and no event is sent; when it resumes, the remaining parts go out and the withdrawal ends completed at the full amount. While it is paused and none of its parts has been signed you can cancel it (withdrawal.cancelled). withdrawal.partially_completed comes only when the destination was blocked during the withdrawal because of fraud or sanctions.
{
"id": "5c2e8f1a-7b3d-4e6f-9a0b-1c2d3e4f5a6b",
"merchant_reference": "payout-5002",
"status": "partially_completed",
"amount": "25000",
"paid_amount": "8333.333334",
"tx_hash": null,
"parts": [
{ "amount": "8333.333334", "status": "completed", "tx_hash": "0x…" },
{ "amount": "8333.333333", "status": "failed", "tx_hash": "0x…" }
],
"…": "…"
}POST/v1/withdrawals/{id}/cancel
Cancel a withdrawal before signing starts (also while it waits for balance or for approval). Send no body.
- Answers
200with the withdrawal, nowcancelled, and sendswithdrawal.cancelled. The lock is released (a withdrawal that waited for balance had none). - After signing has started, once the withdrawal is final, or if it changed state at the same moment:
409 INVALID_STATE. A cancel with a new key on an already cancelled withdrawal is also409. - Repeating with the same
Idempotency-Keyreturns the current state with200.
Webhooks
When something changes we send a POST to your site’s webhook URL. Set the URL in the merchant panel under API and webhook; the panel then shows the signing secret (whsec_…) once. Changing the URL issues a new secret, and undelivered events move to the new URL. Turning the webhook off cancels pending deliveries.
Delivery
- The URL must be
httpson the default port 443, at most 500 characters, without user name, password or#, and must resolve to a public address. Redirects are not followed. - Answer
2xxwithin 10 seconds; any other status, a redirect, a network error or a timeout is a failure. Queue the event and answer at once. - We send to your URL one request at a time, and deliveries to different merchants take turns, so one slow endpoint does not delay the others.
- After 3 timeouts in a row your URL is paused for 60 seconds: deliveries due in that time count as failed without being sent and move to their next retry. After the pause one test delivery goes out; any answer ends the pause.
- The same event can arrive more than once (same
id): process it once. Events can arrive out of order: ignore an event whoseresource_versionis lower than one you already processed for that resource.
Retries
| Attempt | Wait after the previous failure | About this long after the event |
|---|---|---|
| 1 | — | seconds |
| 2 | 1 minute | 1 minute |
| 3 | 5 minutes | 6 minutes |
| 4 | 15 minutes | 21 minutes |
| 5 | 1 hour | 1 hour 21 minutes |
| 6 | 3 hours | 4 hours 21 minutes |
| 7, 8, 9 … | 6 hours each | 10 h 21 min, 16 h 21 min, 22 h 21 min … |
A delivery that fails more than 24 hours after the event is given up (failed). Cryptogon can send it again by hand; the body is then built from the current state.
Verifying the signature
POST /your/webhook/path
Content-Type: application/json
User-Agent: Cryptogon-Webhook/1
X-Cryptogon-Event-Id: 0b8f5a52-2d1c-4c47-9a9b-6a3d2c1e0f11
X-Cryptogon-Timestamp: 1791975960
X-Cryptogon-Signature: v1=<hex HMAC-SHA256(whsec_…, "<timestamp>.<raw body>")>- The HMAC key is the
whsec_…text itself. The signed text is<timestamp>.<raw body>. - Verify against the raw body you received, compare in constant time, and reject events whose timestamp is older than 5 minutes.
Webhook verification
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the exact bytes you received. Do not parse and re-serialise the JSON first.
export function verifyWebhook(secret, headers, rawBody) {
const timestamp = String(headers['x-cryptogon-timestamp'] ?? '');
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const digest = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
const expected = Buffer.from(`v1=${digest}`);
const given = Buffer.from(String(headers['x-cryptogon-signature'] ?? ''));
return given.length === expected.length && timingSafeEqual(given, expected);
}import hashlib, hmac, time
# raw_body: the exact bytes you received. Do not parse and re-serialise the JSON first.
def verify_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
timestamp = headers.get("X-Cryptogon-Timestamp", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
return False
signed = timestamp.encode() + b"." + raw_body
expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, headers.get("X-Cryptogon-Signature", ""))<?php
// $rawBody = file_get_contents('php://input'); — the exact bytes, not re-encoded JSON
function verifyWebhook(string $secret, string $timestamp, string $signature, string $rawBody): bool
{
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) return false;
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}
$ok = verifyWebhook(
getenv('CRYPTOGON_WEBHOOK_SECRET'),
$_SERVER['HTTP_X_CRYPTOGON_TIMESTAMP'] ?? '',
$_SERVER['HTTP_X_CRYPTOGON_SIGNATURE'] ?? '',
file_get_contents('php://input'),
);Body
{
"id": "0b8f5a52-2d1c-4c47-9a9b-6a3d2c1e0f11",
"type": "payment.confirmed",
"created_at": "2026-10-05T12:06:00.000Z",
"resource_version": 3,
"payment_id": "a1b2c3d4-0000-4000-8000-000000000004",
"data": { "id": "6f1c2a7e-…", "merchant_reference": "order-7781234", "status": "confirmed", "…": "…" }
}data is the resource as it was when the event was sent, the same view as the API (GET /v1/deposits/{id}, GET /v1/deposit-sessions/{id}, GET /v1/withdrawals/{id}, without the checkout link). A late event therefore already carries the newest state: decide by data.status, not by type. resource_version counts the events of one resource, starting at 1. payment.* events also carry payment_id: the payment the event was written for (null in payment.expired).
{
"id": "7c41d2e0-5b8a-4f3e-9d6c-2a1b0e9f8d7c",
"type": "withdrawal.rejected",
"created_at": "2026-10-14T10:13:20.000Z",
"resource_version": 1,
"data": {
"id": "0d4b7a6e-1c2f-4e3a-9b8c-7d6e5f4a3b2c",
"merchant_reference": "payout-5001",
"status": "rejected",
"tx_hash": null,
"fees": null,
"rejection_reason": "insufficient_funds",
"…": "…"
}
}Events
| Type | When |
|---|---|
payment.detected | A payment for a session is on chain, not final |
payment.confirmed | The payment that pays the session is final; the winner is in data.payment. Answering it with 2xx lets us credit your balance |
payment.extra | A payment is final but held (session already paid, late payment, or no valuation). Do not credit it |
payment.released | We reviewed and released a held payment of a paid or expired session: it now has credit_status: pending. Credit it, keyed by the payment’s id. (Released into an unpaid session, it pays the session and payment.confirmed is sent instead) |
payment.dropped | A detected payment disappeared before it was final |
payment.expired | The session expired without a payment |
deposit.detected | A transfer for a deposit request is on chain |
deposit.confirmed | Final. Variance in data.transfer.variance. Answering it with 2xx lets us credit your balance with the net amount |
deposit.dropped | A detected transfer disappeared before it was final; the request stays open |
deposit.expired | The request expired without a payment |
withdrawal.pending_approval | Waiting for a decision. Sent again when a withdrawal moves from your review to Cryptogon’s |
withdrawal.sent | Broadcast (data.tx_hash; split withdrawal: once, at the first part, see data.parts) |
withdrawal.completed | Final on chain |
withdrawal.partially_completed | Split withdrawal whose destination was blocked for fraud or sanctions: data.paid_amount was paid, the rest is back |
withdrawal.rejected | Rejected before sending (by a rule, by you, after 72 hours, by Cryptogon, or when the balance wait ended); the lock is released. data.rejection_reason is set only for withdrawals rejected while waiting for balance |
withdrawal.failed | Could not be sent, or failed on chain; the lock is released |
withdrawal.cancelled | Cancelled by you before signing |
site.funded | A top-up of your site balance is final and credited (no commission) |
site.funding_held | A top-up is final but held (data.hold_reason); sent again if the reason changes |
credit.requested … credit.written_off | Credit lifecycle: requested, approved, rejected, cancelled, request expired, repayment, repaid, written off |
Internal steps send no event: waiting for balance, approval by the rules, waiting for a liquidity reservation, signing. The parts of a split withdrawal send none either; the withdrawal itself sends one withdrawal.sent at the first part and one final event.
Balance credit
- Every minute we credit the net amount of final deposits whose confirming event (
deposit.confirmedorpayment.confirmed) your URL has answered with2xx. Thencredit_statusbecomescreditedandcommission.credited_atis set. Because the body is built at sending time, the event itself may still showcredited_at: null; read the resource for the final state. - No webhook URL: the credit waits. Every delivery of the confirming event failed for 24 hours:
credit_statusbecomesfailedand Cryptogon reviews it; after the event has been delivered again the credit goes through. - If Cryptogon pauses crediting, or the payment’s stablecoin is off its peg, events are still delivered; the credit waits until the pause ends.
Crediting rules for payment sessions
Every payment.* body is the full session at the time of sending and does not say which payment the event is about. Credit by looking at the payments in the body, not at the event type:
- Look at every payment in
data.paymentanddata.extra_payments. Credit only those withstatus: confirmedandcredit_statuspendingorcredited. Credit the payment’sorder_value.value, not the order amount. - Credit each payment exactly once, keyed by its
id(the deposit ID), whatever event it came with. Store payment IDs, not event IDs: the same payment appears in several events, and itscredit_statusturns frompendingtocreditedonce your balance is credited. A released extra payment is a second credit for the samemerchant_reference. - Never credit
credit_status: held, and never credit a value you do not recognise.failedmeans only that our event never reached you; wait until it is delivered again. - Ignore unknown event types and unknown fields.
payment.*events go only to sites that open payment sessions.
For a deposit request, credit transfer.amount once per request id when data.status is confirmed; a request takes only one transfer.
Errors
Errors share one shape. Some carry extra fields (for example reason, required, min_amount). The message text is for people and may change: decide by code.
{ "error": { "code": "INVALID_ADDRESS", "message": "…", "reason": "checksum" } }| HTTP | code | When |
|---|---|---|
| 400 | INVALID_REQUEST | The body is not a JSON object; a missing, unknown or invalid field; expires_in out of range; a reference starting with cg:; the merchant_reference query parameter missing |
| 400 | INVALID_AMOUNT | An amount sent as a number, zero, with too many decimals, or (session) not matching the currency’s minor units |
| 400 | IDEMPOTENCY_KEY_REQUIRED, INVALID_IDEMPOTENCY_KEY | The header is missing or malformed |
| 401 | UNAUTHORIZED | Missing header, malformed or unknown key ID, key of the other environment, closed key, timestamp outside 5 minutes, wrong signature; also a key closed while the request was running |
| 403 | SITE_NOT_ACTIVE | Your site is not active (suspended or closed) |
| 403 | INSUFFICIENT_SCOPE | The key lacks the scope for this endpoint |
| 403 | IP_NOT_ALLOWED | The request came from an address outside the key’s list |
| 404 | NOT_FOUND | Unknown path, an ID that is not a UUID, a record that does not exist or belongs to another site |
| 409 | DUPLICATE_REFERENCE | The merchant_reference is already used with different content (or by a session, for a deposit request, and the other way round) |
| 409 | OPEN_DEPOSIT_EXISTS | The customer has an open request or session address in this asset |
| 409 | INVALID_STATE | Cancel not possible: signing started, already final, or the state changed at the same moment |
| 413 | INVALID_REQUEST | The body is larger than 64 KB |
| 415 | INVALID_REQUEST | Content-Type is not application/json |
| 421 | MISDIRECTED_REQUEST | The host name is not one of our API addresses |
| 422 | ASSET_NOT_AVAILABLE | The network or asset is not open in this environment or for your site |
| 422 | INVALID_ADDRESS | Destination address invalid (reason: format, checksum, network), or one of our own addresses or a token contract (no reason) |
| 422 | INSUFFICIENT_NETWORK_BALANCE | Withdrawal, only on a site with balance waiting turned off. Carries required, available, fee, network_reserve |
| 422 | AMOUNT_TOO_SMALL | TRON withdrawal or quote below the gross minimum, or a part does not exceed the fee ceiling. Carries network_fee_max, min_amount, min_net, parts |
| 422 | CURRENCY_NOT_SUPPORTED, AMOUNT_OUT_OF_RANGE, NO_PAYMENT_OPTION | Payment session: currency not enabled for your site, amount above your limit, or nothing to offer |
| 422 | IDEMPOTENCY_KEY_REUSED | The Idempotency-Key was used with a different request |
| 429 | RATE_LIMITED | Too many requests; retry after Retry-After seconds |
| 500 | INTERNAL | Unexpected error on our side; nothing is written. Retry with the same Idempotency-Key |
| 503 | SERVICE_PAUSED | Cryptogon paused address issuing: deposit requests, sessions and customer addresses |
| 503 | ADDRESS_NOT_READY | The customer’s address is not ready yet |
| 503 | RATE_UNAVAILABLE | No current rate: for a native-coin deposit, or for the withdrawal fee |
| 503 | ASSET_PAUSED | The stablecoin is off its peg; new deposits in it are paused |
| 503 | FEE_UNAVAILABLE, FX_UNAVAILABLE | The TRON network fee or the currency rate cannot be computed right now; Retry-After: 60 |
Code examples
A complete signed request that opens a payment session, in four languages. Each one was run against our own signature check. Set CRYPTOGON_KEY_ID and CRYPTOGON_SECRET from the merchant panel; leave CRYPTOGON_API unset to use the sandbox.
Signed request
import { createHash, createHmac } from 'node:crypto';
const API = process.env.CRYPTOGON_API ?? 'https://api-sandbox.cryptogon.dev';
const KEY_ID = process.env.CRYPTOGON_KEY_ID; // test_… in the sandbox, live_… in production
const SECRET = process.env.CRYPTOGON_SECRET; // 43 characters; used to sign, never sent
async function cryptogon(method, path, payload, idempotencyKey) {
const body = payload === undefined ? '' : JSON.stringify(payload);
const timestamp = String(Math.floor(Date.now() / 1000));
const bodyHash = createHash('sha256').update(body).digest('hex');
const signature = createHmac('sha256', SECRET)
.update([timestamp, method, path, bodyHash].join('\n'))
.digest('hex');
const headers = {
'X-Cryptogon-Key': KEY_ID,
'X-Cryptogon-Timestamp': timestamp,
'X-Cryptogon-Signature': `v1=${signature}`,
};
if (body) headers['Content-Type'] = 'application/json';
if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
const res = await fetch(API + path, { method, headers, body: body || undefined });
const json = await res.json();
if (!res.ok) throw new Error(`${res.status} ${json.error?.code}`);
return json;
}
const session = await cryptogon(
'POST',
'/v1/deposit-sessions',
{ merchant_reference: 'order-1001', player_id: 'customer-42', amount: '500.00', currency: 'TRY' },
'order-1001',
);
console.log(session.checkout_url); // redirect your customer hereimport hashlib, hmac, json, os, time
import requests
API = os.environ.get("CRYPTOGON_API", "https://api-sandbox.cryptogon.dev")
KEY_ID = os.environ["CRYPTOGON_KEY_ID"] # test_… in the sandbox, live_… in production
SECRET = os.environ["CRYPTOGON_SECRET"].encode() # used to sign, never sent
def cryptogon(method, path, payload=None, idempotency_key=None):
body = b"" if payload is None else json.dumps(payload, separators=(",", ":")).encode()
timestamp = str(int(time.time()))
body_hash = hashlib.sha256(body).hexdigest()
text = "\n".join([timestamp, method, path, body_hash]).encode()
signature = hmac.new(SECRET, text, hashlib.sha256).hexdigest()
headers = {
"X-Cryptogon-Key": KEY_ID,
"X-Cryptogon-Timestamp": timestamp,
"X-Cryptogon-Signature": "v1=" + signature,
}
if body:
headers["Content-Type"] = "application/json"
if idempotency_key:
headers["Idempotency-Key"] = idempotency_key
res = requests.request(method, API + path, headers=headers, data=body or None, timeout=15)
res.raise_for_status()
return res.json()
session = cryptogon(
"POST",
"/v1/deposit-sessions",
{"merchant_reference": "order-1001", "player_id": "customer-42", "amount": "500.00", "currency": "TRY"},
idempotency_key="order-1001",
)
print(session["checkout_url"]) # redirect your customer here<?php
// test_… in the sandbox, live_… in production; the secret is used to sign and never sent
$api = getenv('CRYPTOGON_API') ?: 'https://api-sandbox.cryptogon.dev';
function cryptogon(string $method, string $path, ?array $payload = null, ?string $idempotencyKey = null): array
{
global $api;
$body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$text = implode("\n", [$timestamp, $method, $path, hash('sha256', $body)]);
$headers = [
'X-Cryptogon-Key: ' . getenv('CRYPTOGON_KEY_ID'),
'X-Cryptogon-Timestamp: ' . $timestamp,
'X-Cryptogon-Signature: v1=' . hash_hmac('sha256', $text, getenv('CRYPTOGON_SECRET')),
];
if ($body !== '') $headers[] = 'Content-Type: application/json';
if ($idempotencyKey !== null) $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
$ch = curl_init($api . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
if ($body !== '') curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode((string) $response, true);
if ($status >= 400) throw new RuntimeException($status . ' ' . ($json['error']['code'] ?? ''));
return $json;
}
$session = cryptogon('POST', '/v1/deposit-sessions', [
'merchant_reference' => 'order-1001',
'player_id' => 'customer-42',
'amount' => '500.00',
'currency' => 'TRY',
], 'order-1001');
echo $session['checkout_url'], PHP_EOL; // redirect your customer hereAPI=${CRYPTOGON_API:-https://api-sandbox.cryptogon.dev}
BODY='{"merchant_reference":"order-1001","player_id":"customer-42","amount":"500.00","currency":"TRY"}'
TS=$(date +%s)
HASH=$(printf '%s' "$BODY" | sha256sum | cut -d' ' -f1)
SIG=$(printf '%s\nPOST\n/v1/deposit-sessions\n%s' "$TS" "$HASH" \
| openssl dgst -sha256 -hmac "$CRYPTOGON_SECRET" | sed 's/^.* //')
curl -sS "$API/v1/deposit-sessions" \
-H "X-Cryptogon-Key: $CRYPTOGON_KEY_ID" \
-H "X-Cryptogon-Timestamp: $TS" \
-H "X-Cryptogon-Signature: v1=$SIG" \
-H "Idempotency-Key: order-1001" \
-H "Content-Type: application/json" \
--data-raw "$BODY"Webhook signature verification, in three languages:
Webhook verification
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the exact bytes you received. Do not parse and re-serialise the JSON first.
export function verifyWebhook(secret, headers, rawBody) {
const timestamp = String(headers['x-cryptogon-timestamp'] ?? '');
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const digest = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
const expected = Buffer.from(`v1=${digest}`);
const given = Buffer.from(String(headers['x-cryptogon-signature'] ?? ''));
return given.length === expected.length && timingSafeEqual(given, expected);
}import hashlib, hmac, time
# raw_body: the exact bytes you received. Do not parse and re-serialise the JSON first.
def verify_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
timestamp = headers.get("X-Cryptogon-Timestamp", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
return False
signed = timestamp.encode() + b"." + raw_body
expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, headers.get("X-Cryptogon-Signature", ""))<?php
// $rawBody = file_get_contents('php://input'); — the exact bytes, not re-encoded JSON
function verifyWebhook(string $secret, string $timestamp, string $signature, string $rawBody): bool
{
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) return false;
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}
$ok = verifyWebhook(
getenv('CRYPTOGON_WEBHOOK_SECRET'),
$_SERVER['HTTP_X_CRYPTOGON_TIMESTAMP'] ?? '',
$_SERVER['HTTP_X_CRYPTOGON_SIGNATURE'] ?? '',
file_get_contents('php://input'),
);Changelog
Changes you can see from outside, newest first. Dates are when the change went live in production (UTC). Fields and events are only ever added; existing ones keep their meaning.
| Date | Change |
|---|---|
| 2026-10-19 | Split withdrawals: pausing no longer ends a split withdrawal short. A paused split withdrawal waits (processing, or sent after its first part), keeps its reservation and sends no event; when it resumes it completes at the full amount. A split withdrawal always ends at the full amount; the only exception is a destination blocked during the withdrawal because of fraud or sanctions (partially_completed). A paused split withdrawal with no signed part can be cancelled. |
| 2026-10-18 | Split withdrawals: no part is sent until Cryptogon has reserved on-chain liquidity for the full amount. While it waits the withdrawal stays processing and can still be cancelled. |
| 2026-10-18 | Documentation corrected to match the code: credit a payment whose credit_status is pending or credited; wait while it is failed (a delivered payment turns credited within about a minute, so reading it later is still valid). |
| 2026-10-18 | Closing a key can wait 1–7 days so you can switch to a new key without downtime; “close now” stays available (Rotating and closing keys). |
| 2026-10-18 | The per-address rate limit counts version 6 addresses per /64 network. |
| 2026-10-18 | Cryptogon applies no amount limit of its own to withdrawals: your auto-approval limit decides (at most 5,000 USD from the merchant panel). On a site with no approver, your holds wait for Cryptogon instead of being skipped. Cryptogon can decide on your behalf (Approval). |
| 2026-10-16 | Each request is bound to its key until it finishes: a key closed in the meantime gets 401 UNAUTHORIZED and nothing is written. |
| 2026-10-15 | Two withdrawal requests with the same merchant_reference at the same moment: the second returns the existing withdrawal (200) or 409 DUPLICATE_REFERENCE, never 500. |
| 2026-10-14 | Waiting for balance: a withdrawal your balance does not cover waits up to 12 minutes (default) instead of 422 INSUFFICIENT_NETWORK_BALANCE; new field rejection_reason; cancelling while it waits. Expiry reasons are fair: service_unavailable if your balance was enough when the window ended. |
| 2026-10-14 | Rate limits with 429 RATE_LIMITED and Retry-After. Webhook delivery: 10-second timeout, one request at a time per URL, 60-second pause after 3 timeouts in a row. |
| 2026-10-10 | TRON withdrawals: the customer pays the network fee (fees.network_fee_payer, player_network_fee_max, player_network_fee, net_amount); POST /v1/withdrawals/quote; 503 FEE_UNAVAILABLE; 422 AMOUNT_TOO_SMALL with a gross minimum of 10 USD (min_amount; 10 units for USD-pegged assets). |
| 2026-10-09 | A deposit’s net amount reaches your available balance once your URL has answered its confirming event with 2xx. |
| 2026-10-08 | Withdrawal fees: the fees object; INSUFFICIENT_NETWORK_BALANCE carries required, available, fee, network_reserve; 503 RATE_UNAVAILABLE for the withdrawal fee. The allowed address list became optional for every scope. |
| 2026-10-07 | Deposit commission: transfer.commission and each payment’s commission. Your own withdrawal approval (pending_approval waits for you; 72 hours without a decision rejects; the event is sent again when the withdrawal moves to Cryptogon). cg: reserved at the start of merchant_reference. Late payments tied to sessions, payment.released and payment_id. credit.* events. Keys and webhook managed in the merchant panel. |
| 2026-10-06 | Payment sessions (/v1/deposit-sessions, payment.*) and GET /v1/currencies. Top-up events site.funded and site.funding_held. |
| 2026-10-05 | Hosted checkout page with checkout_url and the payment window (pay_until). Withdrawals: one approval is final; holds for an inactive site and a blocklisted destination. |
| 2026-10-04 | Webhooks. GET /v1/rates, the 15-minute rate lock, 503 ASSET_PAUSED and 503 RATE_UNAVAILABLE. |
| 2026-10-03 | First release: signed requests, deposit requests, withdrawals, customer addresses, GET /v1/assets. |
Example keys, signatures, IDs and addresses on this page are made up. Sandbox keys are issued during onboarding.