Developer docs

Developers

API documentation

Everything you need to accept crypto deposits and send withdrawals from your own server: signed requests, a hosted checkout page and signed webhooks.

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

EnvironmentBase URLAPI keys
Productionhttps://api.cryptogon.devlive_…
Sandbox (test networks, no real money)https://api-sandbox.cryptogon.devtest_…

Networks and assets

NetworkProduction codeAssetsSandbox codeSandbox assets
TRONtronUSDT, TRXtron_nileUSDT, TRX
BNB Smart ChainbscUSDT, USDC, BNBbsc_testnetBNB
EthereumethereumUSDT, USDC, ETHethereum_sepoliaUSDC, 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)

  1. Your server opens a payment session with POST /v1/deposit-sessions: the amount, the currency (TRY, EUR, USDT …) and your own order reference.
  2. 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.
  3. The customer sends the payment. We watch the chain and wait until the transfer is final.
  4. You receive payment.detected and then payment.confirmed webhooks. Answer each with 2xx.
  5. 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 answered payment.confirmed with 2xx.

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

  1. Optional: POST /v1/withdrawals/quote shows the network fee and the minimum the customer will receive.
  2. POST /v1/withdrawals with the destination address and amount. The answer is 201 with status: processing. If your balance is short, the withdrawal waits for balance for up to 12 minutes (default) and still shows processing.
  3. 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.
  4. We sign and broadcast it: withdrawal.sent with tx_hash.
  5. withdrawal.completed when it is final on chain. If it is rejected, cancelled or fails, you get withdrawal.rejected, withdrawal.cancelled or withdrawal.failed and 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.confirmed or payment.confirmed) with 2xx; we check every minute. commission.credited_at shows 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 sessionMeaning
awaiting_selectionThe customer has not chosen a coin and network yet
awaiting_paymentChosen; waiting for the payment
detectedA payment is on chain but not final
confirmedThe payment is final; credit it (crediting rules under Webhooks)
expiredTime ran out and no payment arrived
Deposit requestMeaning
pendingWaiting for the payment
detectedThe transfer is on chain but not final
confirmedFinal; transfer.variance tells you exact, under or over
expiredTime ran out and no payment arrived
WithdrawalMeaning
processingAccepted and on its way: also while it waits for balance, after approval and while it is being signed
pending_approvalWaiting 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)
sentBroadcast; tx_hash is set (on a split withdrawal: in parts)
completedFinal on chain
partially_completedSplit 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
rejectedRejected before sending; the lock is released (rejection_reason says why for withdrawals rejected while waiting for balance)
cancelledCancelled by you before signing
failedCould 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 number 100.5.
  • Every request that moves money carries an Idempotency-Key; retrying with the same key and body is always safe.
  • merchant_reference is your own transaction ID: 1–100 characters of letters, digits and _ . : -, unique per site. player_id is 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 id and trust data.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.

Deposit lifecycle (payment session)Session opened: awaiting_selection, no event, Wait. Coin and network chosen: awaiting_payment, no event, Wait. Seen on chain: detected, payment.detected, Wait. Final: confirmed, payment.confirmed, Credit. Expired: expired, payment.expired, Nothing to do. Dropped before final: awaiting_payment, payment.dropped, Wait. Extra or late payment: confirmed, payment.extra, Nothing to do. Released after review: confirmed, payment.released, Credit.Session openedawaiting_selectionno eventWaitCoin and networkchosenawaiting_paymentno eventWaitSeen on chaindetectedpayment.detectedWaitFinalconfirmedpayment.confirmedCreditExpiredexpiredpayment.expiredNothing to doDropped before finalawaiting_paymentpayment.droppedWaitnot alwaysExtra or late paymentconfirmedpayment.extraNothing to donot alwaysReleased after reviewconfirmedpayment.releasedCredit
StepstatusWebhookDeposit requestWhenWhat you do
Session openedawaiting_selectionno eventpending · no eventThe 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 chosenawaiting_paymentno eventn/aThe 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 chaindetectedpayment.detecteddetected · deposit.detectedA transfer is on chain but not final yet.Wait Show it as pending to the customer; do not credit yet.
Finalconfirmedpayment.confirmedconfirmed · deposit.confirmedThe 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).
Expiredexpiredpayment.expiredexpired · deposit.expiredTime ran out with no transfer seen: the choice window and every chosen address (request: expires_at).Nothing to do Nothing to credit.
Dropped before finalawaiting_paymentpayment.droppedpending · deposit.droppedA seen transfer disappeared from the chain. The session or request stays open for a new transfer.Wait Do not credit.
Extra or late paymentconfirmedpayment.extran/aA 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 reviewconfirmedpayment.releasedn/aCryptogon 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_EXISTS while 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 as expired (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.value is the received amount in the session currency, rounded down; in a deposit request transfer.amount is the received amount and transfer.variance says exact, under or over.
  • 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) with payment.extra and 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_PAUSED and address is null; 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

Withdrawal lifecycleWaiting for balance: processing, no event, Wait. Accepted, balance locked: processing, no event, Wait. Waiting for approval: pending_approval, withdrawal.pending_approval, Wait. Sent to the network: sent, withdrawal.sent, Wait. Completed: completed, withdrawal.completed, Done. Balance wait ended: rejected, withdrawal.rejected, Give back. Cancelled by you: cancelled, withdrawal.cancelled, Give back. Rejected: rejected, withdrawal.rejected, Give back. Failed: failed, withdrawal.failed, Give back.not alwaysWaiting for balanceprocessingno eventWaitAccepted, balancelockedprocessingno eventWaitnot alwaysWaiting for approvalpending_approvalwithdrawal.pending_approvalWaitSent to the networksentwithdrawal.sentWaitCompletedcompletedwithdrawal.completedDoneBalance wait endedrejectedwithdrawal.rejectedGive backCancelled by youcancelledwithdrawal.cancelledGive backRejectedrejectedwithdrawal.rejectedGive backFailedfailedwithdrawal.failedGive back
StepstatusWebhookWhenWhat you do
Waiting for balanceprocessingno eventYour 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 lockedprocessingno eventAmount and fees are locked; your limits and Cryptogon’s checks run.Wait Wait for the next event.
Waiting for approvalpending_approvalwithdrawal.pending_approvalHeld 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 networksentwithdrawal.senttx_hash is set. It can no longer be cancelled.Wait Wait for the result.
Completedcompletedwithdrawal.completedFinal on chain.Done Mark the payout as paid.
Balance wait endedrejectedwithdrawal.rejectedThe 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 youcancelledwithdrawal.cancelledCancelled before signing started (also while waiting for balance or approval).Give back Return the amount to your customer.
Rejectedrejectedwithdrawal.rejectedBy 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.
Failedfailedwithdrawal.failedCould 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}/cancel works 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 is 409 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 processing to rejected and 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.sent comes once, at the first part, and a single final event ends it; fees.network_fee is the sum of the parts. If Cryptogon pauses it, the remaining parts wait and the withdrawal stays processing (sent once 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), or failed if 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 processing and 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.

Withdrawal approvalAccepted and checked: processing, no event, Wait. Waiting for you: pending_approval, withdrawal.pending_approval, Wait. Waiting for Cryptogon: pending_approval, withdrawal.pending_approval, Wait. Approved: processing, no event, Wait. Rejected by your rule: rejected, withdrawal.rejected, Give back. Declined or timed out: rejected, withdrawal.rejected, Give back. Declined by Cryptogon: rejected, withdrawal.rejected, Give back.Accepted and checkedprocessingno eventWaitnot alwaysWaiting for youpending_approvalwithdrawal.pending_approvalWaitnot alwaysWaiting for Cryptogonpending_approvalwithdrawal.pending_approvalWaitApprovedprocessingno eventWaitRejected by your rulerejectedwithdrawal.rejectedGive backDeclined or timed outrejectedwithdrawal.rejectedGive backDeclined by Cryptogonrejectedwithdrawal.rejectedGive back
StepstatusWebhookWhenWhat you do
Accepted and checkedprocessingno eventRight 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 youpending_approvalwithdrawal.pending_approvalAt 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 Cryptogonpending_approvalwithdrawal.pending_approvalNo 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.
Approvedprocessingno eventNo hold, or approved. Next: sending (withdrawal.sent).Wait Wait for withdrawal.sent.
Rejected by your rulerejectedwithdrawal.rejectedAbove 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 outrejectedwithdrawal.rejectedYou (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 Cryptogonrejectedwithdrawal.rejectedCryptogon declined a withdrawal it held.Give back Return the amount to your customer.
RuleSet byResult
Auto-approval limit: the USD value is at or above it, or the value is unknownYou, in the merchant panel (Limits); at most 5,000 USD there, default 5,000 USD. Cryptogon can set a higher limit or turn it offWaits for you (pending_approval)
Per-withdrawal maximumYouRejected at once (withdrawal.rejected); waits for you if the USD value is unknown
Per-customer daily amount, daily count, hourly countYou (off by default)Waits for you or is rejected, as you choose
First withdrawal, new address, a deposit in the last N minutesYou (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 blocklistCryptogonWaits 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_approval is sent again with a higher resource_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

Waiting for balance: timelineMinute 0: the withdrawal is accepted and answers processing, with no event. Every minute until minute 12 the balance is checked, in request order. If the balance is enough, for example at minute 5, the amount is locked, the fees are fixed and the withdrawal continues as usual. If not, the run after minute 12, usually within a minute, rejects it: withdrawal.rejected with rejection_reason.Waiting window: 12 minutes by default01234567891011121314minutesRequest: processinga balance check every minuteBalance arrives (here: minute 5)Locked, fees fixed, then normal flow:withdrawal.pending_approval or .sentWindow over: rejected in the next runwithdrawal.rejected, status rejected,rejection_reason says why
TimeStepstatusWebhookWhat you do
0Request accepted 201 with processing and fees: null; no event.processingno eventWait Wait.
every minuteBalance checks In request order per asset; a later request never overtakes an earlier one.processingno eventWait Top up if you want it paid.
when your balance is enoughBalance arrives The amount is locked and fees are fixed; it continues like any accepted withdrawal.processingno eventWait Wait for the next event.
any time while it waitsYou cancel POST /v1/withdrawals/{id}/cancel.cancelledwithdrawal.cancelledGive back Return the amount to your customer.
while it waitsDeclined by a person rejection_reason: declined (Cryptogon or a user of your panel; also a TRON withdrawal that no longer meets the minimum).rejectedwithdrawal.rejectedGive back Return the amount to your customer.
after 12 minutes, usually within one moreWindow ends rejection_reason: insufficient_funds, rate_unavailable, service_unavailable or internal_error. Never paid afterwards.rejectedwithdrawal.rejectedGive 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 fees is null.
  • 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_reason after 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) or internal_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_ or test_ followed by 30 letters and digits, 35 characters): sent openly with every request. Production accepts only live_ keys, the sandbox only test_ 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.
ScopeAllows
readReading deposit requests, payment sessions, withdrawals and currencies; withdrawal quotes
depositOpening deposit requests and payment sessions, customer addresses; reading deposit requests, sessions and currencies
withdrawOpening and cancelling withdrawals, reading them; withdrawal quotes
settlementReserved for settlements (not available yet)
any scopeGET /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 UNAUTHORIZED like any invalid key.
  • If a key closes between our signature check and the end of your request, the request gets 401 UNAUTHORIZED and nothing is written; retry with the new key.

Signing a request

Every request carries three headers:

HeaderValue
X-Cryptogon-KeyYour key ID
X-Cryptogon-TimestampUnix time in whole seconds; at most 5 minutes away from our clock
X-Cryptogon-Signaturev1= + 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.

Signing 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)>
Request headers
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 (otherwise 415); the body may be at most 64 KB (otherwise 413).
  • 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

  1. Host name: 421 MISDIRECTED_REQUEST.
  2. Requests per client address (before the signature is checked): 429 RATE_LIMITED.
  3. Body type and size: 415 or 413, both with code INVALID_REQUEST.
  4. Headers, key and signature: 401 UNAUTHORIZED.
  5. Your site is active: 403 SITE_NOT_ACTIVE.
  6. The key has the scope: 403 INSUFFICIENT_SCOPE.
  7. The request comes from an allowed address: 403 IP_NOT_ALLOWED.
  8. The body is a JSON object: 400 INVALID_REQUEST.
  9. Requests per site: 429 RATE_LIMITED.
  10. Fields, Idempotency-Key and 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 are 200.
  • 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 with 200, even when two requests arrive at the same moment. The same reference with different content is 409 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_in is 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 (decimals in GET /v1/assets).
  • Fiat amounts follow the currency’s minor units (minor_units in GET /v1/currencies): "500.00" TRY, "5000" JPY. Trailing zeros are fine ("500.00" JPY is 500); extra decimals are rejected, not rounded.

Rate limits

LimitPer minuteCounts
Per client address1,800Every request, before the signature is checked. Version 6 addresses count per /64 network
Per site1,200Every signed request of your site
Per site, creating300POST /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.

Scope
any key
Response
{
  "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.

Scope
any key
Response
{
  "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_usd is the exchange price. If it drifts 1% or more from 1 USD, available becomes false and new deposits in that asset get 503 ASSET_PAUSED.
  • If a native coin (ETH, BNB, TRX) has no reliable rate, usd is null and new requests get 503 RATE_UNAVAILABLE.

GET/v1/currencies

The fiat currencies your site accepts for payment sessions.

Scope
read or deposit
Response
{
  "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.

Scope
deposit
Request
{
  "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
}
FieldRule
merchant_referenceRequired. Your transaction ID, unique per site (shared with deposit requests)
player_idRequired. Your ID for the customer; the customer’s deposit addresses are permanent per ID
currencyRequired. 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
amountOptional decimal string. Without it the customer sends any amount. Above your limit: 422 AMOUNT_OUT_OF_RANGE
optionsOptional, 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_inSeconds the customer has to choose: 300–1800, default 1800
Response · 201 Created
{
  "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):

JSON
"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 basis is identity and 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_at minus a network margin (1 minute on TRON and BSC, 3 on Ethereum). The address is shown until then; a transfer seen before expires_at still counts. address is null while 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:

JSON
"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. null before the payment is final. basis is locked, identity (crypto session), confirm_rate (late payment) or unavailable (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) or held with hold_reason (extra_payment, late_payment, no_valuation). Never credit held.
  • commission: our deposit commission, taken in the payment’s own coin. order_value stays gross; your balance grows by net.

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.

Scope
read or deposit

POST/v1/deposits

Open a deposit request in an asset you choose.

Scope
deposit
Request
{
  "merchant_reference": "order-1001",
  "player_id": "customer-42",
  "network": "bsc",
  "asset": "USDT",
  "amount": "100.5",
  "expires_in": 1800
}
  • amount is 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 as expired and the new one opens.
  • While address issuing is paused, new requests and repeats get 503 SERVICE_PAUSED.
Response · 201 Created
{
  "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 have rate: null (1 USD).
  • Transfer. Once a transfer is seen, transfer shows tx_hash, amount (received), status, variance, credit_status (pending, credited, failed), detected_at, confirmed_at and commission.
  • Commission. When the deposit is final, transfer.commission shows our commission in the deposit’s coin; your balance grows by net. amount stays gross.
  • Address. address is null on 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 answers 404.
transfer.commission
"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.

Scope
read or deposit

POST/v1/players/{player_id}/addresses

The customer’s permanent deposit address on one network, for reconciliation. Answers 200; creates the customer if needed.

Scope
deposit
Request
{ "network": "tron" }
Response
{ "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.

Scope
read or withdraw
Request
{ "network": "tron", "asset": "USDT", "amount": "100" }
Response
{
  "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", and net_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_net is 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_UNAVAILABLE with Retry-After.

POST/v1/withdrawals

Send crypto to your customer’s address.

Scope
withdraw
Request
{
  "merchant_reference": "payout-5001",
  "player_id": "customer-42",
  "network": "bsc",
  "asset": "USDT",
  "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "amount": "10"
}
Response · 201 Created
{
  "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 repeat 200). 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_ADDRESS with reason (format, checksum or network). Lower-case EVM addresses are accepted and stored in EIP-55 form. Our own deposit addresses and token contracts are refused with 422 INVALID_ADDRESS without reason.
  • merchant_reference cannot start with cg: (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_fee returns to your balance.
fees on TRON
"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.

Scope
read or withdraw

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.

Split withdrawal, destination blocked after one part
{
  "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.

Scope
withdraw
  • Answers 200 with the withdrawal, now cancelled, and sends withdrawal.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 also 409.
  • Repeating with the same Idempotency-Key returns the current state with 200.

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 https on 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 2xx within 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 whose resource_version is lower than one you already processed for that resource.

Retries

AttemptWait after the previous failureAbout this long after the event
1—seconds
21 minute1 minute
35 minutes6 minutes
415 minutes21 minutes
51 hour1 hour 21 minutes
63 hours4 hours 21 minutes
7, 8, 9 …6 hours each10 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

Webhook request
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

Node.js
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);
}
Python
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
<?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

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

withdrawal.rejected after waiting for balance
{
  "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

TypeWhen
payment.detectedA payment for a session is on chain, not final
payment.confirmedThe payment that pays the session is final; the winner is in data.payment. Answering it with 2xx lets us credit your balance
payment.extraA payment is final but held (session already paid, late payment, or no valuation). Do not credit it
payment.releasedWe 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.droppedA detected payment disappeared before it was final
payment.expiredThe session expired without a payment
deposit.detectedA transfer for a deposit request is on chain
deposit.confirmedFinal. Variance in data.transfer.variance. Answering it with 2xx lets us credit your balance with the net amount
deposit.droppedA detected transfer disappeared before it was final; the request stays open
deposit.expiredThe request expired without a payment
withdrawal.pending_approvalWaiting for a decision. Sent again when a withdrawal moves from your review to Cryptogon’s
withdrawal.sentBroadcast (data.tx_hash; split withdrawal: once, at the first part, see data.parts)
withdrawal.completedFinal on chain
withdrawal.partially_completedSplit withdrawal whose destination was blocked for fraud or sanctions: data.paid_amount was paid, the rest is back
withdrawal.rejectedRejected 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.failedCould not be sent, or failed on chain; the lock is released
withdrawal.cancelledCancelled by you before signing
site.fundedA top-up of your site balance is final and credited (no commission)
site.funding_heldA top-up is final but held (data.hold_reason); sent again if the reason changes
credit.requested … credit.written_offCredit 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.confirmed or payment.confirmed) your URL has answered with 2xx. Then credit_status becomes credited and commission.credited_at is set. Because the body is built at sending time, the event itself may still show credited_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_status becomes failed and 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:

  1. Look at every payment in data.payment and data.extra_payments. Credit only those with status: confirmed and credit_status pending or credited. Credit the payment’s order_value.value, not the order amount.
  2. 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 its credit_status turns from pending to credited once your balance is credited. A released extra payment is a second credit for the same merchant_reference.
  3. Never credit credit_status: held, and never credit a value you do not recognise. failed means only that our event never reached you; wait until it is delivered again.
  4. 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.

JSON
{ "error": { "code": "INVALID_ADDRESS", "message": "…", "reason": "checksum" } }
HTTPcodeWhen
400INVALID_REQUESTThe 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
400INVALID_AMOUNTAn amount sent as a number, zero, with too many decimals, or (session) not matching the currency’s minor units
400IDEMPOTENCY_KEY_REQUIRED, INVALID_IDEMPOTENCY_KEYThe header is missing or malformed
401UNAUTHORIZEDMissing 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
403SITE_NOT_ACTIVEYour site is not active (suspended or closed)
403INSUFFICIENT_SCOPEThe key lacks the scope for this endpoint
403IP_NOT_ALLOWEDThe request came from an address outside the key’s list
404NOT_FOUNDUnknown path, an ID that is not a UUID, a record that does not exist or belongs to another site
409DUPLICATE_REFERENCEThe merchant_reference is already used with different content (or by a session, for a deposit request, and the other way round)
409OPEN_DEPOSIT_EXISTSThe customer has an open request or session address in this asset
409INVALID_STATECancel not possible: signing started, already final, or the state changed at the same moment
413INVALID_REQUESTThe body is larger than 64 KB
415INVALID_REQUESTContent-Type is not application/json
421MISDIRECTED_REQUESTThe host name is not one of our API addresses
422ASSET_NOT_AVAILABLEThe network or asset is not open in this environment or for your site
422INVALID_ADDRESSDestination address invalid (reason: format, checksum, network), or one of our own addresses or a token contract (no reason)
422INSUFFICIENT_NETWORK_BALANCEWithdrawal, only on a site with balance waiting turned off. Carries required, available, fee, network_reserve
422AMOUNT_TOO_SMALLTRON 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
422CURRENCY_NOT_SUPPORTED, AMOUNT_OUT_OF_RANGE, NO_PAYMENT_OPTIONPayment session: currency not enabled for your site, amount above your limit, or nothing to offer
422IDEMPOTENCY_KEY_REUSEDThe Idempotency-Key was used with a different request
429RATE_LIMITEDToo many requests; retry after Retry-After seconds
500INTERNALUnexpected error on our side; nothing is written. Retry with the same Idempotency-Key
503SERVICE_PAUSEDCryptogon paused address issuing: deposit requests, sessions and customer addresses
503ADDRESS_NOT_READYThe customer’s address is not ready yet
503RATE_UNAVAILABLENo current rate: for a native-coin deposit, or for the withdrawal fee
503ASSET_PAUSEDThe stablecoin is off its peg; new deposits in it are paused
503FEE_UNAVAILABLE, FX_UNAVAILABLEThe 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

Node.js
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 here
Python
import 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
<?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 here
cURL
API=${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

Node.js
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);
}
Python
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
<?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.

DateChange
2026-10-19Split 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-18Split 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-18Documentation 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-18Closing 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-18The per-address rate limit counts version 6 addresses per /64 network.
2026-10-18Cryptogon 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-16Each request is bound to its key until it finishes: a key closed in the meantime gets 401 UNAUTHORIZED and nothing is written.
2026-10-15Two 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-14Waiting 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-14Rate 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-10TRON 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-09A deposit’s net amount reaches your available balance once your URL has answered its confirming event with 2xx.
2026-10-08Withdrawal 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-07Deposit 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-06Payment sessions (/v1/deposit-sessions, payment.*) and GET /v1/currencies. Top-up events site.funded and site.funding_held.
2026-10-05Hosted 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-04Webhooks. GET /v1/rates, the 15-minute rate lock, 503 ASSET_PAUSED and 503 RATE_UNAVAILABLE.
2026-10-03First 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.