> ## 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 or 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 both the asset and network exactly.

<Warning>
  Sending the wrong token, using the wrong network, or omitting a required reference can make funds
  unrecoverable or require manual investigation. 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, account name, and any required
        payment reference.
      </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 for the exact stablecoin and network. An address issued for one
        network is not permission to use it on another.
      </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.

```bash theme={null}
curl -X POST https://api.sandbox.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": "Transfer Treasury"
  }'
```

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

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

## 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.wayex.com/v1/treasury/balances \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY"
```

Check the asset, network where applicable, `available`, `reserved`, `pending`, and `asOf`. 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.wayex.com/v1/treasury/payins \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY"

# Stablecoin detected on issued addresses
curl https://api.sandbox.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.