# Relay (/reference/relay)

## The rate card a rental is charged at

`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.

### Responses

- `200` — The rate card.
  - `object` (required, string)
  - `enabled` (required, boolean) — False while new rentals are paused. Existing rentals keep forwarding.
  - `period_fee_cents_per_day` (required, integer) — USD cents per started 24 h of window, for YOUR account (a negotiated price applies here; 0 = rentals are free).
  - `fee_bps` (required, integer) — Our take from each forwarded payment, in basis points, for YOUR account (300 = 3%; 0 = none). Charged on top of the per-day window.
  - `grace_premium_bps` (required, integer) — What an extension made in grace costs on top, in basis points (5000 = +50%).
  - `min_period_hours` (required, integer)
  - `max_period_hours` (required, integer)
  - `chains` (required, array, of string) — The networks a rental can be made on. Each payment is moved into platform custody and forwarded from there, which needs a keyless account with a direct send.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — `missing_scope` — the key lacks `relay:read`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Your rented relay addresses, newest first

`GET /v1/relay/rents`

### Parameters

- `limit` (query, optional, integer)
- `cursor` (query, optional, string) — Opaque cursor from the previous page's `next_cursor`.

### Responses

- `200` — Rents.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `ref` (required, string) — The public `MOLN-…` reference quoted to support.
    - `chain` (required, string)
    - `asset` (required, string)
    - `direction` (required, string, one of: receive, send) — `receive`: the destination is yours. `send`: it is a recipient's, and the fallback is your refund address.
    - `status` (required, string, one of: active, grace, retired, canceled)
    - `phase` (required, string, one of: active, grace, retired) — Where the deadline clock stands right now.
    - `address_known` (required, boolean)
    - `address` (required, string | null) — The rented deposit address — hand this to the payer.
    - `destination` (required, object)
      - `address` (required, string)
      - `memo` (required, string | null)
    - `fallback` (required, object)
      - `address` (required, string)
      - `memo` (required, string | null)
    - `active_until` (required, string (date-time))
    - `grace_until` (required, string (date-time)) — Forwarding still works in grace; after this, arrivals go to the fallback.
    - `period_hours` (required, integer)
    - `period_fee_cents` (required, integer) — One period's price, as billed. Set by the rate card.
    - `fee_bps` (required, integer) — Our take from each forwarded payment, in basis points (300 = 3%), fixed when the rental was made. Comes off the payment before the network fee; the rest is forwarded.
    - `extension_count` (required, integer)
    - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — `missing_scope` — the key lacks `relay:read`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Rent a fresh deposit address for a window

`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.

### Request body (required)

- `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
- `asset` (required, string) — A coin `GET /v1/chains` lists on that chain, e.g. `USDT`. Case-insensitive; stored as the catalogue spells it.
- `period_hours` (required, integer) — Billed as whole started days at the rate card (`GET /v1/relay/pricing`).
- `destination` (required, object)
  - `address` (required, string)
  - `memo` (optional, string) — REQUIRED on TON, where a forward without it lands in the void. Refused on chains whose transfers carry no memo (`supports_memo: false` on `GET /v1/chains`).
- `fallback` (required, object)
  - `address` (required, string)
  - `memo` (optional, string)
- `direction` (optional, string, one of: receive, send) — `receive`: a payer sends to the rented address and it forwards to YOUR destination. `send`: you pay into the rented address and it is delivered to someone else's destination; the fallback is then your refund address. Same machinery and price either way.
- `idempotency_key` (optional, string) — Retry-safe creation: a repeat with the same key returns the first rental and is charged once.

### Responses

- `201` — The rental, its address, and the deadlines.
  - `object` (required, string)
  - `ref` (required, string) — The public `MOLN-…` reference quoted to support.
  - `chain` (required, string)
  - `asset` (required, string)
  - `direction` (required, string, one of: receive, send) — `receive`: the destination is yours. `send`: it is a recipient's, and the fallback is your refund address.
  - `status` (required, string, one of: active, grace, retired, canceled)
  - `phase` (required, string, one of: active, grace, retired) — Where the deadline clock stands right now.
  - `address_known` (required, boolean)
  - `address` (required, string | null) — The rented deposit address — hand this to the payer.
  - `destination` (required, object)
    - `address` (required, string)
    - `memo` (required, string | null)
  - `fallback` (required, object)
    - `address` (required, string)
    - `memo` (required, string | null)
  - `active_until` (required, string (date-time))
  - `grace_until` (required, string (date-time)) — Forwarding still works in grace; after this, arrivals go to the fallback.
  - `period_hours` (required, integer)
  - `period_fee_cents` (required, integer) — One period's price, as billed. Set by the rate card.
  - `fee_bps` (required, integer) — Our take from each forwarded payment, in basis points (300 = 3%), fixed when the rental was made. Comes off the payment before the network fee; the rest is forwarded.
  - `extension_count` (required, integer)
  - `created_at` (required, string (date-time))
- `400` — `invalid_body`.
- `401` — Missing, malformed, expired or revoked API key.
- `402` — `insufficient_funds` — the prepaid balance cannot cover the window; top up under Money.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `422` — `unsupported_chain`, `relay_unsupported_chain` (relay runs only where a keyless account can send — see `chains` on `GET /v1/relay/pricing`), `unsupported_asset` (not a coin on that chain), `asset_unavailable` (not open for new addresses or payouts right now), `invalid_period`, `invalid_address`, `self_payout_forbidden` (an address held by this service), `memo_required` on a chain that demands one, or `memo_not_supported` on a chain with no memo field.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## One rental and its credits

`GET /v1/relay/rents/{ref}`

### Parameters

- `ref` (path, required, string)

### Responses

- `200` — The rental, and every credit that arrived on it with where each stands.
  - `rent` (required, object)
    - `object` (required, string)
    - `ref` (required, string) — The public `MOLN-…` reference quoted to support.
    - `chain` (required, string)
    - `asset` (required, string)
    - `direction` (required, string, one of: receive, send) — `receive`: the destination is yours. `send`: it is a recipient's, and the fallback is your refund address.
    - `status` (required, string, one of: active, grace, retired, canceled)
    - `phase` (required, string, one of: active, grace, retired) — Where the deadline clock stands right now.
    - `address_known` (required, boolean)
    - `address` (required, string | null) — The rented deposit address — hand this to the payer.
    - `destination` (required, object)
      - `address` (required, string)
      - `memo` (required, string | null)
    - `fallback` (required, object)
      - `address` (required, string)
      - `memo` (required, string | null)
    - `active_until` (required, string (date-time))
    - `grace_until` (required, string (date-time)) — Forwarding still works in grace; after this, arrivals go to the fallback.
    - `period_hours` (required, integer)
    - `period_fee_cents` (required, integer) — One period's price, as billed. Set by the rate card.
    - `fee_bps` (required, integer) — Our take from each forwarded payment, in basis points (300 = 3%), fixed when the rental was made. Comes off the payment before the network fee; the rest is forwarded.
    - `extension_count` (required, integer)
    - `created_at` (required, string (date-time))
  - `credits` (required, array)
    - `object` (required, string)
    - `ref` (required, string)
    - `status` (required, string, one of: detected, scheduled, forwarded, refunded, failed)
    - `asset` (optional, string) — The coin that ARRIVED — usually the rental's. A different coin sent to the address is forwarded as itself.
    - `amount_atomic` (required, string)
    - `decimals` (optional, integer)
    - `tx_hash` (optional, string)
    - `from_address` (optional, string | null)
    - `attempts` (optional, integer)
    - `explorer_url` (optional, string | null) — The arrival on a block explorer.
    - `forward_payout_id` (optional, string | null)
    - `forward_tx_hash` (optional, string | null)
    - `intake` (optional, object | null) — The move from the rented address into the platform's forwarding wallet. Every leg out is paid from there, never from the rented address. Null until it is planned.
      - `status` (optional, string) — planned, broadcast, confirmed, failed…
      - `tx_hash` (optional, string | null)
      - `explorer_url` (optional, string | null)
      - `landed_at` (optional, string | null (date-time)) — When it was in custody; the forward is scheduled after this.
    - `forward` (optional, object | null) — The leg out — the forward, or the fallback once that lane took the credit. Null until it is scheduled.
      - `to` (optional, string, one of: destination, fallback)
      - `status` (optional, string) — The payout's status: queued (waiting for its random delay), broadcast, confirmed, failed…
      - `amount_atomic` (optional, string) — What leaves: the arrival minus our fee and the network fee (none on the fallback leg).
      - `fee_atomic` (optional, string) — Our take (`fee_bps`), in the arrived coin's atomic units.
      - `network_fee_atomic` (optional, string) — The network fee recovered from the payment, in the same units.
      - `release_at` (optional, string | null (date-time)) — When the delay lets it go.
      - `tx_hash` (optional, string | null)
      - `explorer_url` (optional, string | null)
    - `settled_to` (optional, string | null) — Set on the fallback lane: where the credit actually went.
    - `last_error` (optional, string | null) — Why a FAILED credit stopped. Null while it is still on its way.
    - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — `missing_scope` — the key lacks `relay:read`.
- `404` — no such rental on this tenant.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Buy more window, now

`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.

### Parameters

- `ref` (path, required, string)

### Request body (required)

- `hours` (required, integer)

### Responses

- `200` — The extended rental.
  - `object` (required, string)
  - `ref` (required, string) — The public `MOLN-…` reference quoted to support.
  - `chain` (required, string)
  - `asset` (required, string)
  - `direction` (required, string, one of: receive, send) — `receive`: the destination is yours. `send`: it is a recipient's, and the fallback is your refund address.
  - `status` (required, string, one of: active, grace, retired, canceled)
  - `phase` (required, string, one of: active, grace, retired) — Where the deadline clock stands right now.
  - `address_known` (required, boolean)
  - `address` (required, string | null) — The rented deposit address — hand this to the payer.
  - `destination` (required, object)
    - `address` (required, string)
    - `memo` (required, string | null)
  - `fallback` (required, object)
    - `address` (required, string)
    - `memo` (required, string | null)
  - `active_until` (required, string (date-time))
  - `grace_until` (required, string (date-time)) — Forwarding still works in grace; after this, arrivals go to the fallback.
  - `period_hours` (required, integer)
  - `period_fee_cents` (required, integer) — One period's price, as billed. Set by the rate card.
  - `fee_bps` (required, integer) — Our take from each forwarded payment, in basis points (300 = 3%), fixed when the rental was made. Comes off the payment before the network fee; the rest is forwarded.
  - `extension_count` (required, integer)
  - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — no such rental on this tenant.
- `422` — `rental_retired` — lapsed rentals do not extend; rent a new address.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Cancel before any money arrives

`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`.

### Parameters

- `ref` (path, required, string)

### Responses

- `200` — The canceled rental.
  - `object` (required, string)
  - `ref` (required, string) — The public `MOLN-…` reference quoted to support.
  - `chain` (required, string)
  - `asset` (required, string)
  - `direction` (required, string, one of: receive, send) — `receive`: the destination is yours. `send`: it is a recipient's, and the fallback is your refund address.
  - `status` (required, string, one of: active, grace, retired, canceled)
  - `phase` (required, string, one of: active, grace, retired) — Where the deadline clock stands right now.
  - `address_known` (required, boolean)
  - `address` (required, string | null) — The rented deposit address — hand this to the payer.
  - `destination` (required, object)
    - `address` (required, string)
    - `memo` (required, string | null)
  - `fallback` (required, object)
    - `address` (required, string)
    - `memo` (required, string | null)
  - `active_until` (required, string (date-time))
  - `grace_until` (required, string (date-time)) — Forwarding still works in grace; after this, arrivals go to the fallback.
  - `period_hours` (required, integer)
  - `period_fee_cents` (required, integer) — One period's price, as billed. Set by the rate card.
  - `fee_bps` (required, integer) — Our take from each forwarded payment, in basis points (300 = 3%), fixed when the rental was made. Comes off the payment before the network fee; the rest is forwarded.
  - `extension_count` (required, integer)
  - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — no such rental on this tenant.
- `422` — `rental_has_credits`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.