Declare a member deposit

The only endpoint in the system that creates member balance from a declaration. All six gates are required:

1. Mandatory signature, even when this Key has signature_required=false. Missing x-signature / x-timestamp / x-nonce always returns 401. Timestamp tolerance is ±300 seconds, and nonces cannot be replayed.
2. The idempotency key must carry a tenant prefix, and the merchant must supply a business reference (reference). Reporting the same on-chain receipt twice would otherwise double-credit it.
3. Per-transaction and daily cumulative limits, configured per merchant by central administration.
4. The asset must be allowed for the merchant; unknown assets are rejected rather than left pending.
5. Platform risk controls and eligibility still apply; deposit declaration does not bypass them.
6. Full audit trail and visibility in the merchant portal.

The journal has two legs: member.available credit W / merchant.custody debit W. merchant.available does not participate; declaring a deposit is not a business cost.

Two keys: do not confuse them

• x-idempotency-key, a UUID in the header, protects against network retries: the same key and body replay the original result for 24 hours; the same key with a different body returns 409.
• reference in the body protects against reporting one on-chain receipt twice: it forms the ledger idempotency key mdep:<商户>:<reference>, regardless of whether you change the request idempotency key. reference must therefore be a stable identifier for that receipt, such as txid + vout or your deposit order number. Do not generate a new one on every call.

A duplicate returns 200 + replayed: true; the first successful posting returns 201. replayed tells you the deposit was already recorded without comparing balances.

On-chain provenance: four optional fields, persisted when supplied

network / txid / from_address / to_address document the funds' origin. Under merchant_hosted, we do not observe the chain, so only you can supply them. Without them, our ledger's sole trace for the newly created member balance is your reference. This blocks three situations: a member denies depositing while you say they did, leaving us unable to substantiate either account; a regulator asks for the source and we have no txid; or the deposit needs an originating address and there is no from_address to attach.

• All four are optional: offline deposits, such as fiat receipts or internal transfers, genuinely have none.
• However, txid or either address requires network, otherwise returns 400 invalid_fields. A txid without a known chain is effectively no txid: it cannot be checked in an explorer or used to answer an inquiry, despite appearing to provide provenance. The same 0x… string on BSC / ETH / Polygon identifies three different accounts.
• network has no allowlist: this chain is part of your own receiving infrastructure. Restricting it to our chain catalog would prevent truthful declarations until we added each new chain. It is automatically uppercased.
• On repeated declarations with the same reference, provenance follows the same rule as amounts: the first submission wins. Later values do not overwrite it. The response echoes the stored values, not the latest input; echoing input would falsely suggest a new txid was accepted.

⚠ txid is not deduplicated, and should not be. One chain transaction can contain multiple deposits, such as several UTXO vout outputs, ERC-20 batch transfers, or exchange consolidations. Deduplication always uses reference.

Allowlist semantics

No rows means the merchant has not enabled an allowlist, so the platform asset catalog applies. Once any row exists, each asset must match its own enabled row. An absent asset row means rejected, not no configured limit.

Handling failures

• On 504 / network timeout, retry with the same x-idempotency-key; we may already have posted the deposit.
• On a definite 4xx, use a new key; the same key replays the failure unchanged.
• On limit_exceeded, inspect limit_type: single for per-transaction or daily for daily cumulative limits. Retrying cannot resolve it; check limits in the merchant portal.

Prerequisites

• The request is signed; mandatory here regardless of the Key's signature_required setting.
• The asset is in the platform catalog and enabled; if the merchant has an allowlist, the asset must also have a matching enabled row.
• The member is not banned, blocklisted, or frozen; platform eligibility checks still apply.

Request Headers

Request Body

Response

{
  "id": "dep_0xa3f1c2e9-0",
  "reference": "0xa3f1c2e9-0",
  "external_member_id": "u_10023",
  "asset": "USDT",
  "amount": "1500.000000",
  "ledger_scale": 6,
  "status": "credited",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "replayed": true
}

{
  "id": "dep_0xa3f1c2e9-0",
  "reference": "0xa3f1c2e9-0",
  "external_member_id": "u_10023",
  "asset": "USDT",
  "amount": "1500.000000",
  "ledger_scale": 6,
  "status": "credited",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "replayed": false
}