POST/v1/deposits

Create a deposit

Creates a new deposit intent. The response includes a freshly generated, single-use address on the requested chain. Funds sent to that address are credited to the merchant's internal balance for the corresponding asset.

Always send an Idempotency-Key so retries are safe. The request body must be JSON (Content-Type: application/json).

Parameters

stringRequired

Asset to receive. Must be one of ETH, USDT, BTC, TRX.

stringRequired

Chain family to receive on. Must be one of ethereum, tron, bitcoin, and compatible with asset.

stringOptional

Optional expected amount, as a decimal string with up to 8 fractional digits. When provided, the deposit is marked underpaid or overpaid depending on the actual amount received.

stringOptional

Your own identifier for this deposit (e.g. order ID). 1–255 chars. Returned on every webhook event for this deposit.

stringOptional

Per-deposit webhook URL (http(s), max 2000 chars). Overrides the account-level webhook endpoints for events related to this deposit.

stringOptional

ISO-8601 timestamp at which the deposit address window closes. If omitted, the default 30-minute window is used.

objectOptional

Free-form key/value pairs echoed back on the deposit object and on all related webhook events.

Returns

Returns the created Deposit object with status: "pending".

Errors

Status	Code	Description
400	`invalid_request_error`	Parameter missing, invalid, or `asset`/`chain` combination not supported.
401	`authentication_error`	Missing or invalid API key.
409	`idempotency_key_reused`	The `Idempotency-Key` was previously used with a different request body.

Create a deposit

curl https://api.aeses.io/v1/deposits \
-H "x-api-key: sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
  "asset": "USDT",
  "chain": "ethereum",
  "amount": "99.50",
  "reference_id": "ord_4421",
  "webhook_url": "https://example.com/webhooks/aeses"
}'

Response

{
"object": "deposit",
"id": "dep_01hxyz7m2p5rt4vg3k8aqwe9fn",
"status": "pending",
"asset": "USDT",
"chain": "ethereum",
"expected_amount": "99.50",
"received_amount": null,
"deposit_address": "0x8f3a9c2bF7e1A4d62D8b9fF6E3c5a7E1d2B4c8A9",
"reference_id": "ord_4421",
"webhook_url": "https://example.com/webhooks/aeses",
"metadata": null,
"tx_hash": null,
"confirmations": 0,
"expires_at": 1731600000,
"created_at": 1731598200
}