Create a crypto top-up deposit

POST

/deposit

Returns a dedicated deposit address and QR code for a flexible crypto top-up. Requires cryptoCurrencyCode and merchant orderId. The account comes from the API key.

Required scope: deposits.create.

Authorizations

• TENANT_API_KEY

Request Body^required

Media typeapplication/json

object

cryptoCurrencyCode

required

Crypto currency code.

string

Allowed values: USDT_TRC20 USDT_ERC20 USDT_BEP20 USDC_ERC20 USDC_BEP20 USDC_BASE EURC_BASE LINK_ERC20 LINK_BEP20 ETH TRX BNB BTC ETH_BASE

Example

USDT_TRC20

orderId

required

Merchant idempotency key (unique per account).

string

customerId

Optional merchant customer reference.

string

webhookUrl

HTTPS webhook for deposit status events. Overrides tenant default deposit webhook.

string

Example

https://merchant.example.com/webhooks/cryptonly/deposits

Responses

201

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

minimumAmount

required

number

address

required

string

createdAt

required

ISO 8601 — when the deposit address window started.

string

expiresAt

required

ISO 8601 expiry for the deposit address.

string

qrCode

required

PNG QR code as a data URL (data:image/png;base64,…).

string

Example ^generated

{
  "data": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "minimumAmount": 1,
    "address": "example",
    "createdAt": "example",
    "expiresAt": "example",
    "qrCode": "example"
  }
}

400

Request validation failed (e.g. missing or malformed body / query).

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

401

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

403

Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope).

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

409

A deposit with the same orderId already exists in a terminal state.

429

Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

500

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}