> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.wayex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URL, authentication, conventions, and endpoint explainers for the Wayex REST API.

The Wayex API is resource-oriented, returns JSON, and uses standard HTTP verbs and status codes. The
OpenAPI document is generated from the application and enriched with client-facing workflow context.

## Base URL

```text theme={null}
https://api.sandbox.wayex.com
```

Current endpoints are versioned under `/v1`.

## Authentication and account isolation

Send a tenant-bound API key as `Authorization: Bearer <key>` or `X-Api-Key: <key>`. Secret keys can
perform permitted writes; publishable keys are read-only.

The key determines the tenant account. A request cannot choose another tenant in its body.
Separate tenant accounts have separate keys, wallets, configuration, webhooks, and reporting. See
[Authentication](/authentication).

## Two integration models

### Direct payment routes

Create a route under an onboarded customer and share its reusable funding instructions. A funding
event automatically creates a transfer, prices at the live rate, converts, and delivers funds. The
Rates API is indicative and never binds this workflow.

Read [Payment routes](/console/payment-routes) for the full flow.

### Treasury

Prefund an isolated tenant wallet in AUD or supported stablecoin. Then create beneficiaries and AUD
payouts, request and accept exact conversion quotes, and withdraw stablecoin to saved destinations.

`accepted` means validation passed and the full source debit was durably reserved. Bank,
blockchain, trade, and post-trade settlement remain asynchronous. A conversion credits the
destination wallet only after physical provider funds arrive.

Read the [Treasury overview](/treasury/overview) before integrating.

## Find the endpoint you need

The API reference is organized by workflow. Expand **Core workflows** for the endpoints needed to
fund a wallet, pay AUD, convert balances, withdraw stablecoin, or create a direct payment route.

Expand **Advanced API** when you need list and detail lookups, lifecycle actions, reconciliation,
webhook diagnostics, credentials, or reporting. These endpoints remain fully documented without
crowding the launch path.

## Conventions

* **Idempotency** — send an `Idempotency-Key` on supported `POST`/`PUT` writes and preserve it across
  retries. `PATCH`/`DELETE` retry rules appear on their endpoint pages.
* **Money** — amounts are exact decimal strings with an explicit asset; never parse them as floating
  point.
* **Networks** — treat asset and network as one pair. Never infer a network from an address.
* **References** — store the Wayex resource ID and relevant external settlement references. Supply
  `externalReference` only where your own system has a stable business identifier; Wayex generates
  one for supported resources when it is omitted.
* **Lists** — use server filters and cursors when exposed. Do not fetch a short window and treat it as
  a complete ledger.
* **Webhooks** — deliveries are at-least-once and unordered. Deduplicate, then fetch current state.
* **Errors** — branch on stable `code` and log `requestId`; never parse human-readable messages.

## What every endpoint page explains

Each generated endpoint page includes:

1. what the endpoint does;
2. when to use it;
3. prerequisites and required access;
4. money and wallet effect;
5. important states and what completion means;
6. retry and idempotency behavior;
7. a link to the relevant end-to-end guide.

This content is enforced by the public-spec generator. An endpoint cannot be published without a
complete explainer entry.

## Resources

| Resource             | Description                                                                  |
| -------------------- | ---------------------------------------------------------------------------- |
| **Customers**        | Onboard and verify end users for direct payment routes.                      |
| **Payment routes**   | Issue reusable customer funding instructions for automatic on-ramp/off-ramp. |
| **Transfers**        | Read conversions created by direct-route funding events.                     |
| **Rates**            | Read current indicative conversion rates.                                    |
| **Treasury**         | Fund, pay, convert, withdraw, and reconcile one isolated tenant wallet.      |
| **Webhooks**         | Subscribe to signed asynchronous updates and inspect deliveries.             |
| **API keys**         | Create, restrict, rotate, and revoke tenant-bound credentials.               |
| **Fees and revenue** | Manage developer fees and report earned revenue.                             |
| **Invoices**         | Reconcile issued billing records and line items.                             |
| **Invitations**      | Activate staff access to a tenant account.                                   |

Choose a workflow in the navigation or download the complete OpenAPI specification from the page
menu.

<Warning>
  The sandbox URL may be connected to controlled live-provider rails for an explicitly enabled
  tenant. Never fund an instruction until Wayex confirms the environment, asset/network, and limit.
</Warning>