# API documentation (/api)



MolnPay is a **custodial wallet service and payment gateway**. You create customers, we derive a deposit
address per customer per chain, we watch the chains, credit an internal double-entry ledger when deposits
confirm, notify you by signed webhook, sweep funds into your master wallet, and send payouts on your
instruction.

**What it is not:** not an exchange, not a trading venue, not a fiat on-ramp. It moves crypto and keeps an
accurate ledger. Nothing else.

<Callout title="Addresses have no key">
  A customer's deposit address is a smart account the factory creates at an address known in advance — the
  **same address on every EVM chain**, and no private key anywhere. Only the operator can move its funds,
  and only into destinations you allowed. That is the custody model, and it is why a merchant never holds
  a key for a customer address.
</Callout>

## Where to start [#where-to-start]

| You want to…                                          | Read                                                                              |
| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
| Decide between the wallet service and hosted checkout | [Which product do I need?](/start/which-product)                                  |
| Prove your key works                                  | [Your first call](/start/first-call)                                              |
| Go end to end: customer → address → deposit → payout  | [Quickstart](/start/quickstart)                                                   |
| Receive events and verify them                        | [Webhooks](/guides/webhooks), then [Verify a signature](/guides/verify-signature) |
| Rehearse without real money                           | [Test mode](/guides/test-mode)                                                    |
| See every endpoint and schema                         | [API reference](/reference)                                                       |

## Set up your integration in the dashboard [#set-up-your-integration-in-the-dashboard]

Use **Developers → API keys** to create a credential for your integration. Then register an endpoint
under **Webhooks** so your application can follow payments and wallet activity. The Help Center has
walkthroughs for [API keys](/help-center/api-keys) and [webhook endpoints](/help-center/webhooks).

<AppPicture name="api-keys" alt="The dashboard API keys screen showing separate sample credentials for a storefront, customer wallets, and reporting." caption="Use a separate credential for each integration. The identifiers shown are examples." />

## The five things that will break your integration if you skip them [#the-five-things-that-will-break-your-integration-if-you-skip-them]

These are not style preferences. Each one has a specific, expensive failure mode.

1. **Amounts are decimal strings, never JSON numbers.** `1 ETH` is `1000000000000000000` wei, past
   `Number.MAX_SAFE_INTEGER`. Use a big-integer type end to end. [Money representation](/concepts/money).
2. **USDT and USDC on BSC have 18 decimals. Everywhere else, 6.** `POST /v1/payouts` makes you echo the
   asset's `decimals` and refuses a mismatch. Read them from `GET /v1/chains`; never hardcode 6.
3. **Verify webhook signatures over the raw request body.** Not a re-serialised object. The header is
   `MolnPay-Signature`. [Verify a signature](/guides/verify-signature).
4. **`Idempotency-Key` is mandatory on `POST /v1/payouts`.** A retried POST without one can send funds
   twice. [Idempotency](/concepts/idempotency).
5. **Only `deposit.confirmed` is money — and it can be retracted.** `deposit.detected` means seen on
   chain, and a confirmed deposit can be reorged out (`deposit.orphaned`), in which case you reverse what
   you credited.

## For agents [#for-agents]

The whole contract is machine-readable: [`/openapi.json`](/openapi.json) carries every endpoint, every
schema and every webhook payload, and its `info.description` inlines the same quickstart these guides are
built from. [`/llms.txt`](/llms.txt) indexes this site; append `.md` to any page for its Markdown.