API reference

Relay

Rented deposit addresses: a payer sends to the rented address, every credit inside the window forwards to your real destination from a different MolnPay…

GET/v1/relay/pricing

Your account's live price: period_fee_cents_per_day per started 24 h of window (a 30 h window bills two days), plus fee_bps of every payment that is forwarded — taken from the payment before the network fee, the rest forwarded. Extending in grace costs grace_premium_bps more. enabled: false means new rentals are paused; existing ones keep forwarding.

AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/relay/pricing"
{  "object": "relay_pricing",  "enabled": true,  "period_fee_cents_per_day": 0,  "fee_bps": 0,  "grace_premium_bps": 0,  "min_period_hours": 0,  "max_period_hours": 0,  "chains": [    "string"  ]}
GET/v1/relay/rents
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Query Parameters

limit?integer
Range1 <= value <= 100
Default25
cursor?string

Opaque cursor from the previous page's next_cursor.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/relay/rents"
{  "object": "list",  "has_more": true,  "next_cursor": "string",  "data": [    {      "object": "relay_rent",      "ref": "string",      "chain": "string",      "asset": "string",      "direction": "receive",      "status": "active",      "phase": "active",      "address_known": true,      "address": "string",      "destination": {        "address": "string",        "memo": "string"      },      "fallback": {        "address": "string",        "memo": "string"      },      "active_until": "2019-08-24T14:15:22Z",      "grace_until": "2019-08-24T14:15:22Z",      "period_hours": 0,      "period_fee_cents": 0,      "fee_bps": 0,      "extension_count": 0,      "created_at": "2019-08-24T14:15:22Z"    }  ]}
POST/v1/relay/rents

Mints a fresh deposit address on the chain you name, active for the window you name, billed from your prepaid balance at the rate card (whole started days — an hour bills as one day). Give both a destination (often an exchange deposit address — include its memo where the chain demands one) and a fallback: where money goes if the window lapses or forwarding fails for good. Each credit inside the window forwards automatically on its own delay, minus our fee_bps take (fixed on the rental from GET /v1/relay/pricing) and the network fee; after the window plus its grace, arriving money is held and sent to the fallback instead — it never bounces to the payer.

AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/relay/rents" \  -H "Content-Type: application/json" \  -d '{    "chain": "ethereum",    "asset": "string",    "period_hours": 1,    "destination": {      "address": "string"    },    "fallback": {      "address": "string"    }  }'
{  "object": "relay_rent",  "ref": "string",  "chain": "string",  "asset": "string",  "direction": "receive",  "status": "active",  "phase": "active",  "address_known": true,  "address": "string",  "destination": {    "address": "string",    "memo": "string"  },  "fallback": {    "address": "string",    "memo": "string"  },  "active_until": "2019-08-24T14:15:22Z",  "grace_until": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_fee_cents": 0,  "fee_bps": 0,  "extension_count": 0,  "created_at": "2019-08-24T14:15:22Z"}
GET/v1/relay/rents/{ref}
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Path Parameters

ref*string
Match^MOLN-[A-Z0-9]+$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/relay/rents/string"
{  "rent": {    "object": "relay_rent",    "ref": "string",    "chain": "string",    "asset": "string",    "direction": "receive",    "status": "active",    "phase": "active",    "address_known": true,    "address": "string",    "destination": {      "address": "string",      "memo": "string"    },    "fallback": {      "address": "string",      "memo": "string"    },    "active_until": "2019-08-24T14:15:22Z",    "grace_until": "2019-08-24T14:15:22Z",    "period_hours": 0,    "period_fee_cents": 0,    "fee_bps": 0,    "extension_count": 0,    "created_at": "2019-08-24T14:15:22Z"  },  "credits": [    {      "object": "relay_credit",      "ref": "string",      "status": "detected",      "asset": "string",      "amount_atomic": "string",      "decimals": 0,      "tx_hash": "string",      "from_address": "string",      "attempts": 0,      "explorer_url": "string",      "forward_payout_id": "string",      "forward_tx_hash": "string",      "intake": {        "status": "string",        "tx_hash": "string",        "explorer_url": "string",        "landed_at": "2019-08-24T14:15:22Z"      },      "forward": {        "to": "destination",        "status": "string",        "amount_atomic": "string",        "fee_atomic": "string",        "network_fee_atomic": "string",        "release_at": "2019-08-24T14:15:22Z",        "tx_hash": "string",        "explorer_url": "string"      },      "settled_to": "string",      "last_error": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ]}
POST/v1/relay/rents/{ref}/extend

Adds hours to the LATER of now and the current deadline — extending never bills idle time, and a rental in grace comes back to active. Whole periods at the rental's own period price; a partial period bills whole. In grace the period costs 50% more. The charge books with the extension in one transaction.

AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Path Parameters

ref*string
Match^MOLN-[A-Z0-9]+$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/relay/rents/string/extend" \  -H "Content-Type: application/json" \  -d '{    "hours": 1  }'
{  "object": "relay_rent",  "ref": "string",  "chain": "string",  "asset": "string",  "direction": "receive",  "status": "active",  "phase": "active",  "address_known": true,  "address": "string",  "destination": {    "address": "string",    "memo": "string"  },  "fallback": {    "address": "string",    "memo": "string"  },  "active_until": "2019-08-24T14:15:22Z",  "grace_until": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_fee_cents": 0,  "fee_bps": 0,  "extension_count": 0,  "created_at": "2019-08-24T14:15:22Z"}
POST/v1/relay/rents/{ref}/cancel

Only while no credit has landed. After that the rental is a payout in waiting and cancellation is refused with rental_has_credits.

AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Path Parameters

ref*string
Match^MOLN-[A-Z0-9]+$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/relay/rents/string/cancel"
{  "object": "relay_rent",  "ref": "string",  "chain": "string",  "asset": "string",  "direction": "receive",  "status": "active",  "phase": "active",  "address_known": true,  "address": "string",  "destination": {    "address": "string",    "memo": "string"  },  "fallback": {    "address": "string",    "memo": "string"  },  "active_until": "2019-08-24T14:15:22Z",  "grace_until": "2019-08-24T14:15:22Z",  "period_hours": 0,  "period_fee_cents": 0,  "fee_bps": 0,  "extension_count": 0,  "created_at": "2019-08-24T14:15:22Z"}