# AtlasPay

AtlasPay is a live custodial crypto wallet and payment API for merchants, exchanges, brokers, and AI-enabled products.

Canonical production contract:
- OpenAPI 3.1: https://atlaspay.one/v1/openapi.json
- API changelog: https://atlaspay.one/v1/api-changelog
- Human developer reference: https://atlaspay.one/dashboard/developer

Always read the OpenAPI contract and changelog before generating integration code. Never infer fields from screenshots, old chats, or live traffic.

## Choose one integration mode

### checkout

Use for stores, SaaS, invoices, and one-time payments.

- Create payment orders with POST /v1/orders.
- Redirect the payer to checkout_url.
- Verify order webhooks and reconcile GET /v1/orders/{order_id}.

### exchange_wallet

Use for exchanges, brokers, wallets, and platforms that show deposit and withdrawal pages inside their own product. Do not use hosted checkout.

- Assign one reusable address per external_user_id + chain + currency with POST /v1/deposit-addresses.
- Credit the platform's own user ledger only after a verified wallet.deposit.confirmed webhook.
- Reconcile with GET /v1/deposit-addresses/{deposit_address_id}/transactions or GET /v1/transactions.
- Read balances from GET /v1/wallet-portfolio and asset details from GET /v1/wallet-assets/{asset_key}.
- Quote fees with POST /v1/withdrawal-fee-quote, then create retry-safe requests with POST /v1/withdrawals and X-AtlasPay-Idempotency-Key.
- Treat wallet.withdrawal.completed and wallet.withdrawal.failed as terminal events.
- Human merchant-console users approve or reject withdrawals. Never request or use X-MPC-Sign-Key and never call internal broadcast endpoints.

### hybrid

Use when the project needs both hosted payment orders and reusable user wallet addresses. Implement both contracts and keep order and wallet webhook identities separate.

## AI merchant onboarding

POST https://atlaspay.one/v1/ai/merchant-apply

Set integration_mode to checkout, exchange_wallet, or hybrid. The field is optional; omission preserves the historical checkout behavior.

Store returned ATLASPAY_API_KEY and ATLASPAY_WEBHOOK_SECRET only in backend secrets. Give merchant_console.token_login_url or console_token only to the human owner. Never place credentials in frontend code, browser requests, mobile packages, Git, screenshots, or public logs.

## Shared implementation rules

- Authenticate customer API calls with X-API-Key. AtlasPay derives merchant identity from the key.
- Treat all monetary values as fixed-point decimal strings, never binary floating point.
- Verify X-FACET-SIGNATURE as lowercase hex HMAC-SHA256 over the exact raw HTTP request body.
- Persist X-FACET-EVENT + X-FACET-IDEMPOTENCY-KEY before changing an order or balance.
- Reconcile timed-out writes before retrying. Use the original idempotency key and identical request body.
- Keep a local business ledger. AtlasPay is the authority for custody and chain state, not the project's end-user balance model.
- Do not use Polygon for new orders, addresses, collection, or withdrawals.
- Check GET /v1/wallet-asset-policies before enabling an asset action.

Suggested one-line prompts:

- Checkout: Integrate this project with AtlasPay at https://atlaspay.one in hosted checkout mode.
- Exchange: Integrate this exchange with AtlasPay at https://atlaspay.one in direct wallet mode, no checkout.
- Hybrid: Integrate this project with AtlasPay at https://atlaspay.one using both checkout and reusable user wallet addresses.