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

# Funding and balances

> Fund an isolated Treasury account in AUD or stablecoin and understand when money becomes available.

Funding adds backed money to the tenant account that owns the issued instructions. It does not add
money to another account held by the same legal entity.

## Three records, three purposes

| Resource               | What it represents                                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Funding instrument** | Reusable instructions: an AUD BSB/account (and, by default, a PayID to pay into) or a stablecoin deposit address. |
| **Pay-in or deposit**  | One observed incoming payment with its gross amount, fee, net credit, status, and source references.              |
| **Wallet movement**    | The immutable financial entry created when the incoming payment affects the wallet.                               |

Do not treat a funding instrument as proof that funds arrived, or a detected deposit as spendable.
Only the wallet's `available` amount can fund a new operation.

## Before you fund

* Confirm you are using the login or API key for the intended tenant account.
* Read the effective rails, assets, and networks.
* Fetch the current instructions instead of storing a screenshot or retyping them.
* For stablecoin, match the asset exactly, and use a network the instrument was issued for — its
  single `network`, or one of the `acceptedNetworks` listed on an EVM-scope instrument.

<Warning>
  For stablecoin, sending the wrong token or using a network the instrument was not issued for can
  make funds unrecoverable or require manual investigation. For AUD, pay only the exact issued BSB
  and account number. Never infer compatibility from the address format.
</Warning>

## Fund with AUD or stablecoin

<Tabs>
  <Tab title="AUD">
    <Steps>
      <Step title="Get AUD instructions">
        List the account's funding instruments. Provision an AUD instrument only when a suitable one
        does not already exist. It returns the BSB, account number, and account name, plus — unless
        you opt out — a `payId` that resolves to the same account. Incoming payments are matched by
        the unique BSB and account number — no payment reference is required. A newly issued account
        or PayID can take a few minutes to become active for NPP; honour any `activationMessage`
        before sharing the PayID for a real payment.
      </Step>

      <Step title="Send the payment">
        Pay the exact issued instructions from the approved source. Preserve your own payment
        reference so your operations team can match it later.
      </Step>

      <Step title="Wait for the credit">
        Wayex detects and matches the pay-in, applies any configured inbound fee, then credits the
        net amount when it is usable. Until then it remains pending or held.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Stablecoin">
    <Steps>
      <Step title="Get an asset/network address">
        Use a funding instrument issued for the exact stablecoin, on a network the instrument
        accepts. For a single-network instrument (one with a `network` field), an address issued for
        one network is not permission to use it on another. An EVM-scope instrument (`networkScope:
                        "evm"`) has one address that accepts the asset on any network listed in its returned
        `acceptedNetworks` — never a network outside that list.
      </Step>

      <Step title="Send and preserve the transaction hash">
        Send the supported token and retain the source wallet reference and transaction hash.
      </Step>

      <Step title="Wait for finality and screening">
        Wayex detects the deposit, waits for the required network finality and screening, and
        credits the net amount. A detected or confirming deposit is not available.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Provision funding instructions

Creating instructions does not move money. Use one idempotency key for the logical provisioning
request and keep it stable across retries.

The request `type` selects what to provision, and each type has its own options:

* **`aud_account`** — reusable AUD instructions. `accountName` is required. `includePayId` is an
  optional boolean that defaults to **true**: the instrument is issued with an email PayID to pay
  into alongside the BSB and account number. Set it to `false` to issue the account only.
* **`stable_address`** — a stablecoin deposit address. `asset` is required. Provide a single
  `network` to pin the address to one chain, or `networkScope: "evm"` to accept the asset at one
  address on any supported EVM chain (see the EVM example below).

```bash theme={null}
curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/funding-instruments \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: aud-account-example" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "aud_account",
    "accountName": "Your Company Treasury",
    "includePayId": true
  }'
```

An AUD instrument returns its BSB, account number, and account name and — unless you set
`includePayId` to `false` — a `payId` to pay into. A newly issued account or PayID can take a few
minutes to become active for NPP. When the response carries an `activationMessage`, show it to your
user and wait for activation before sharing the PayID for a real payment; the BSB and account number
can be used as soon as they are issued.

For stablecoin, choose a pair returned by the account's effective settings:

```bash theme={null}
curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/funding-instruments \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: funding-instrument-usdc-base-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stable_address",
    "asset": "USDC",
    "network": "base"
  }'
```

To accept the asset at one address on any supported EVM network, request an EVM-scope instrument
instead of naming a single network:

```bash theme={null}
curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/funding-instruments \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: funding-instrument-usdc-evm-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stable_address",
    "asset": "USDC",
    "networkScope": "evm"
  }'
```

The response returns one deposit address plus `acceptedNetworks`, filled by Wayex with the networks
that address accepts. A deposit on any listed network is processed on the chain it lands on. Always
share the returned list with the payer; funds sent on a network outside it are not accepted.

## Gross, fee, and net credit

Incoming-funding records separate the amount received from the amount credited:

```text theme={null}
gross amount - inbound fee = net wallet credit
```

For example, a gross A$10,000.00 pay-in with a A$5.00 inbound fee credits A\$9,995.00. Do not derive
the fee from a balance difference; read the amounts recorded on the funding resource and linked
wallet movement.

## Funding states

| State        | Spendable?          | What to do                                                     |
| ------------ | ------------------- | -------------------------------------------------------------- |
| `detected`   | No                  | Wait while Wayex identifies and matches the payment.           |
| `confirming` | No                  | Wait for bank usability or blockchain finality and screening.  |
| `held`       | No                  | Read the reason and next action; contact support if requested. |
| `credited`   | Yes, in `available` | Reconcile the net credit and linked wallet movement.           |
| `returned`   | No                  | Reconcile the return and its reason.                           |

Pending money must remain visible as pending. If provider data is stale or unavailable, do not render
it as zero and do not submit work based on a guessed balance.

## Read the balance safely

```bash theme={null}
curl https://api.sandbox.rails.wayex.com/v1/treasury/balances \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY"
```

Check the `asset`, `available`, `reserved`, `pending`, `posted`, and `asOf`. Balance entries never
carry a network — balances are per asset, with stablecoin balances aggregated across networks.
Networks appear on network-specific resources such as funding instruments, deposits, and
withdrawals. A later write can still be rejected if another accepted operation reserves funds
first.

## Read incoming funding

Wayex creates pay-in and deposit records from provider activity. Clients never `POST` a pretend
incoming payment.

```bash theme={null}
# AUD received on issued BSB/account instructions
curl https://api.sandbox.rails.wayex.com/v1/treasury/payins \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY"

# Stablecoin detected on issued addresses
curl https://api.sandbox.rails.wayex.com/v1/treasury/deposits \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY"
```

Open `GET /v1/treasury/payins/{id}` or `GET /v1/treasury/deposits/{id}` for the current reason, next
action, source references, gross/fee/net amounts, and linked movement. A stable deposit also shows the
transaction reference and whether required finality was reached.

Funding instruments have matching list, get, create, and deactivate operations. Deactivation stops
normal new use but preserves historical pay-ins, deposits, and wallet movements.

## Webhooks and retries

Use `treasury.payin.updated` and `treasury.deposit.updated` to trigger a fresh funding-resource read,
and use `treasury.wallet.updated` to refresh balances. Webhooks are at-least-once and unordered:
deduplicate by `eventId`, then fetch the current record rather than applying events as an ordered
ledger.

GET requests can be retried with backoff. For funding-instrument creation or deactivation, retry the
same payload with the same `Idempotency-Key`. Never create a second instrument merely because the
response was lost.

Read [Operations and reconciliation](/treasury/operations-and-reconciliation) before moving from test
funding to live-value operations.