Production contract · 2026-07-20

One contract for humans,agents, and production code.

Hosted checkout, long-term deposit addresses, custodial wallets, collection and approved withdrawals without reverse-engineering live traffic.

AI-readable source of truth

Schema: OpenAPI 3.1
Authentication: X-API-Key
Amounts: decimal strings
Internal signing: not exposed

01 · Quickstart

The safe integration order

Keep credentials and merchant balances in your backend. Browsers and mobile apps call your server, never AtlasPay with a live key.

Apply

POST /v1/ai/merchant-apply and store env values only in your backend.

Hand off

Give the one-time console token only to the human owner.

Verify

Validate raw-body HMAC and deduplicate before ledger changes.

02 · Balance model

Total is not the same as withdrawable

GET /v1/wallet-portfolio?quote=USDT is authoritative. available_balance is collected, uncollected_balance remains in receive addresses, and locked_balance is reserved.

03 · Withdrawal fees

Quote gross amount before creating the request

There is no quote_id. Submit the original amount to POST /v1/withdrawals; AtlasPay recalculates and stores the active policy snapshot.

curl -sS -X POST https://atlaspay.one/v1/withdrawal-fee-quote \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ATLASPAY_API_KEY" \
  -d '{"chain":"TRC20","currency":"USDT","amount":"10.00"}'

{
  "chain": "TRC20",
  "currency": "USDT",
  "fee_currency": "USDT",
  "amount": "10.000000",
  "platform_fee": "0.100000",
  "network_fee": "30.000000",
  "network_fee_asset": "TRX",
  "network_fee_included": false,
  "total_fee": "0.100000",
  "net_amount": "9.900000",
  "platform_fee_bps": 5,
  "model": "native_gas_policy",
  "policy_version": "2026-07-19.2"
}

network_fee uses network_fee_asset. Here 30 means a TRX gas budget, not 30 USDT. Native gas is not deducted from token amount when network_fee_included=false.

04 · Webhooks

Sign the raw body, deduplicate before credit

Verify X-FACET-SIGNATURE as lowercase hex HMAC-SHA256(raw body). Persist X-FACET-IDEMPOTENCY-KEY before applying any balance change.

order.updated

Hosted checkout and order-attributed deposits.

wallet.deposit.confirmed

Confirmed long-term address deposit.

wallet.withdrawal.*

Completed or failed withdrawal.

05 · Errors

Branch on HTTP status

The current body is { error: string }. Treat the message as operator-facing text, not a permanent machine code.

HTTP	Category	Action
400	Invalid request	Fix JSON, precision, address, asset policy or state.
401	Authentication	Provide an active X-API-Key.
403	Forbidden	Human console permission or approval is required.
404	Not found	Verify ownership and resource ID.
409	Conflict	Reconcile the current operation state.
429	Rate limited	Use bounded exponential backoff.
503	Unavailable	Retry reads; reconcile writes first.

06 · Live asset boundary

Fail closed by network and action

Always read GET /v1/wallet-asset-policies. Deposit-live does not imply collection or withdrawal support.

Network	Asset	Gas	Current boundary
TRC20	USDT	TRX	Deposit · collect · withdraw
TRC20	TRX	TRX	Deposit · withdraw
BEP20	USDT	BNB	Deposit · collect · withdraw
BEP20	BNB	BNB	Deposit · withdraw
BEP20	VELNX	BNB	Deposit · collect · withdraw
SOLANA	SOL / USDT	SOL	Explicit deposit only

Contract-first integration

Give the OpenAPI URL directly to your AI.

OpenAPI JSON Changelog