About the API
Base URL, conventions, and the stability promise behind every endpoint.
The pages in this section are generated directly from the MolnPay OpenAPI document, so they describe
exactly what each endpoint accepts and returns. The document itself is published at
/openapi.json if you want to generate a client, a mock server or types from it — and its
info.description inlines the same quickstart these guides are built from, so an agent reading only the
document gets every rule.
Base URL
https://api.molnpay.comEvery endpoint sits under /v1. There is one host; a project is either live (mp… keys, mainnet) or test
(mptest… keys, the chain simulated through /v1/test/*), and the key decides which.
Authentication
One header on every request:
Authorization: Bearer mp<64 hex>mptest<64 hex> for a test project. Keys are minted in the console
and shown once. A missing, malformed, expired or revoked key answers 401 invalid_api_key; a key of the
wrong kind for a route answers 403 wrong_key_kind, because you are authenticated and "use your other
key" is something you can act on. Authentication has the whole scheme.
Conventions
Requests and responses are JSON; send Content-Type: application/json on anything with a body.
Amounts are decimal strings, never JSON numbers. Atomic amounts ("1500000000000000000") come with a
*_decimal twin and the asset's decimals; fiat amounts (price_amount, every *_cents) are integer
minor units, also as strings. Money representation.
Timestamps are RFC 3339, UTC.
Lists are cursor-paginated, newest first. limit 1–100 (default 25), an opaque cursor, and
next_cursor until it comes back null. Pagination.
Idempotency-Key is honoured on every POST and required on payouts. Idempotency.
A not-found and a not-yours answer identically. Another project's customer, endpoint or delivery is a
404, never a 403, so nothing confirms that an id exists.
Every failure uses one envelope: { error, code, type, message, param?, request_id }. Branch on
code; quote request_id when you write to support. Errors.
Stability
The API is versioned in the path at /v1, and webhook envelopes carry api_version. Within a version,
changes are additive: new endpoints, new optional request fields, new response properties, new event types
and new error codes can appear without notice; existing fields do not change meaning or disappear.
Do not use strict object mappers
Because new response properties can appear at any time, a deserializer configured to throw on unknown keys will break on a routine, backwards-compatible change. Configure yours to ignore what it does not recognise, and keep a default branch on every enumerated value.
Where to start
Customers and Wallets are what every wallet-service
integration needs; GET /v1/ping (Meta) is the first call worth making, because it
tells you what your key may do.