> ## 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 URLs

| Environment    | Base URL                              |
| -------------- | ------------------------------------- |
| **Sandbox**    | `https://api.sandbox.rails.wayex.com` |
| **Production** | `https://api.rails.wayex.com`         |

Current endpoints are versioned under `/v1`. Sandbox runs on fully simulated provider rails and
never moves real funds; production moves real value. API keys are issued per environment.

## 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 Wayex approved the request and reserved the full amount, including fees, from
your wallet — it moves from `available` to `reserved`. It does not mean money has moved anywhere
yet: the bank payout, on-chain transfer, or conversion settles asynchronously afterwards. Watch
webhooks or poll the operation until it reaches a final status — `settled`, `failed`, or
`returned`. A conversion credits the destination balance only after settlement completes.

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** — every authenticated `POST`/`PUT` requires an `Idempotency-Key` header;
  requests without one are rejected. Retry a timeout or unknown outcome with the same key and the
  API replays the original response instead of acting twice; reusing a key with different
  parameters is rejected. `PATCH`/`DELETE` retry rules appear on their endpoint pages. See
  [Idempotency](/idempotency).
* **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.
  Supported pairs are enforced fail-closed. **USDC:** `ethereum`, `base`, `arbitrum`, `optimism`,
  `polygon`, `bsc`, `solana`. **USDT:** `ethereum`, `arbitrum`, `optimism`, `avalanche`, `solana`,
  `tron`. Any other pair is rejected `400` with code `unsupported_asset_network`. Treasury
  availability is additionally gated by your account's effective settings
  (`GET /v1/treasury/configurations/effective`) and surfaces as `422` with code
  `asset_network_unavailable`.
* **References** — store the Wayex resource ID from every create response. Some writes require an
  `externalReference` from your own system (for example, Treasury payouts); on others (for
  example, beneficiaries) it is optional and Wayex generates one when omitted. Each endpoint
  page's request schema marks which applies.
* **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>
  Production instructions move real value. Test in sandbox first, then confirm the agreed
  asset/network and limits with Wayex before funding a production instruction.
</Warning>