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

# Automations

> Configure automatic onramps, offramps, and swaps that trigger when funds are received without manual transfer requests.

## Common Automation Flows

* **Fiat to Stablecoin (Onramp)** - Automatically mints stablecoins when a fiat deposit is received.
* **Stablecoin to Fiat (Offramp)** - Automatically converts stablecoins to fiat and withdraws to a bank account. *(Coming Q1 2027)*
* **Stablecoin to Stablecoin (Swap)** - Automatically swaps one stablecoin for another. *(Coming Q3 2026)*

> [!TIP]
>
> Automations can also be created in the Brale Dashboard on the Automations tab.

> [!NOTE]
>
> A USD Automation mints a Brale-issued stablecoin, such as `SBC`, to its destination. Set `destination.value_type` to a Brale-issued stablecoin. USDC is not a supported Automation destination, so a direct USD → USDC Automation is not available. To deliver USDC, see [Onramp to USDC](#onramp-to-usdc).

> [!WARNING]
>
> Automations on a transactional account (`account_type: transactional`) may only target external destinations. A Brale-custodied destination is rejected. See [Account types](https://docs.brale.xyz/key-concepts/account-types.md), [Transactional Accounts](https://docs.brale.xyz/guides/transactional-accounts.md), and [Individual accounts](https://docs.brale.xyz/guides/individual-accounts.md).

## Onramp Automation with Virtual Accounts

Automations provide a unique account number and routing number for wire transfers, ACH deposits, and FedNow credits (on accounts with FedNow enabled). When funds are received, stablecoins are automatically minted to a pre-defined wallet address. Businesses can use automations to direct unique pre-funding coordinates to their customers, which mint stablecoins in a customer's wallet.

Here’s what happens end-to-end when you use an onramp automation:

1. **Create the automation**\
   You define `source.value_type` as `USD` and set a `destination` wallet and stablecoin (e.g., `SBC` on `solana`) via the API or Dashboard.
2. **Virtual account is provisioned**\
   Brale provisions a virtual account and populates `source.funding_instructions` with bank details (routing number, account number, bank name, beneficiary).
3. **Customer sends funds**\
   You share those bank details with your customer. They send a wire, ACH, or FedNow payment to the virtual account. No additional API call is required. See [Receive FedNow deposits](https://docs.brale.xyz/guides/fednow-inbound.md).
4. **Stablecoins are minted automatically**\
   When funds arrive, Brale automatically creates a `Transfer` (USD → stablecoin), mints the stablecoin, and sends it to the `destination.address_id` configured on the automation.
5. **Track activity via Transfers**\
   You can reconcile and monitor all onramp activity by querying Transfers for the account:\
   `GET /accounts/{account_id}/transfers`.\
   Transfers created by automations include `source.payment_details` when Brale has underlying payment metadata to expose. Use this to identify the sender and reconcile inbound fiat payments. See [Transfers — `source.payment_details`](https://docs.brale.xyz/key-concepts/transfers#sourcepayment_details) for details.

## Creating an Automation

Create an automation to receive USD and automatically mint SBC to a Solana wallet.

**POST** `https://api.brale.xyz/accounts/{account_id}/automations`

```json Request theme={null}
{
  "name": "XYZ Onramp",
  "source": {
    "value_type": "USD"
  },
  "destination": {
    "address_id": "35LWXNTO2jem13nXCLyciFdi162",
    "value_type": "SBC",
    "transfer_type": "solana"
  }
}
```

Set `source.value_type` to `USD` and omit `source.transfer_type`. A USD Automation is not tied to one deposit rail. Its virtual account accepts the inbound rails enabled for it, and responses may return `source.transfer_type: null`. The resulting Transfer records the rail that was actually used in `source.transfer_type`, such as `wire`, `ach_credit`, or `fednow_credit`. Existing USD Automations are expected to accept FedNow without recreation when FedNow is enabled.

Automations are created in a `pending` state. Once virtual accounts are created and the automation is ready to use, it transitions to `active`. An `active` Automation is ready to receive deposits. It is not the same as a Transfer reaching `complete`.

```json Response theme={null}
{
  "id": "35kVg1llbsOBYvx9XKr9eOtsD9z",
  "name": "XYZ Onramp",
  "status": "pending",
  "source": {
    "transfer_type": null,
    "value_type": "USD"
  },
  "destination": {
    "transfer_type": "solana",
    "address_id": "35LWXNTO2jem13nXCLyciFdi162",
    "value_type": "SBC"
  },
  "updated_at": "2025-11-20T15:56:03.531196Z",
  "created_at": "2025-11-20T15:56:03.531196Z"
}
```

When an automation becomes active, the `source.funding_instructions` object is populated with the virtual account’s bank details (routing number, account number, beneficiary name, etc.). These are the coordinates you share with your customer to fund the automation.

## Onramp to USDC

To turn a USD deposit into USDC, combine an Automation with a separate swap Transfer:

1. **Mint a Brale-issued stablecoin with an Automation**\
   Create a USD Automation with a Brale-issued stablecoin destination, such as `SBC` on `solana`. See [Creating an Automation](#creating-an-automation). Share the Automation's `source.funding_instructions` with the sender.
2. **Swap to USDC with a Transfer**\
   After the mint Transfer reaches `complete`, create a [stablecoin-to-stablecoin swap](https://docs.brale.xyz/guides/stablecoin-to-stablecoin-swap.md) Transfer from `SBC` to `USDC`. Brale swaps Brale-issued stablecoins and USDC 1:1 without slippage. Set `destination.address_id` to the wallet that should receive the USDC, such as your customer's external address.

**POST** `https://api.brale.xyz/accounts/{account_id}/transfers`

```json Request theme={null}
{
  "amount": {
    "value": "100",
    "currency": "USD"
  },
  "source": {
    "address_id": "35LWXNTO2jem13nXCLyciFdi162",
    "value_type": "SBC",
    "transfer_type": "solana"
  },
  "destination": {
    "address_id": "2VcUIjvaXjMUVAWLT8R9LzEUDed",
    "value_type": "USDC",
    "transfer_type": "solana"
  }
}
```

The swap is not part of the Automation. You create one swap Transfer for each amount you want to convert.

> [!NOTE]
>
> Funding instructions belong to the Automation, not to a token. Find them in `source.funding_instructions` from [Retrieve an Automation](#retrieve-an-automation), or on the Automation in the Brale Dashboard Automations tab. The USDC token view in the Dashboard does not show Automations or funding instructions.

## Branded Automations

Branded Automations let you select the verified identity (business or individual) shown as the beneficiary on funding instructions for a virtual account.

Both custodial and transactional accounts can be used as `brand.account_id`, subject to applicable verification and program eligibility.

| Brand account | Beneficiary shown on funding instructions |
| :- | :- |
| Individual transactional | Individual's legal name and address |
| Individual custodial | Individual's legal name and address |
| Business transactional | Business's verified name and address |
| Business custodial | Business's verified name and address |

Add a `brand` object to the create request to control which account name appears on funding instructions:

| Field | Where | Type | Description |
| :- | :- | :- | :- |
| `brand` | Body | object | `{ "account_id": "<ACCOUNT_ID>" }` — your own account or a managed account (business or individual) whose verified identity will appear as the beneficiary on wire and ACH funding instructions. |

Behavior:

* Set `brand` with the [Create Automation](https://docs.brale.xyz/api-reference/brale/create-automations.md) API. Automations created in the Brale Dashboard do not have a brand option, so their funding instructions show Brale as the beneficiary.
* If `brand` is omitted, the beneficiary on funding instructions remains Brale.
* If `brand.account_id` references a business account, `beneficiary_name` and `beneficiary_address` show the business name and address.
* If `brand.account_id` references an individual account, `beneficiary_name` and `beneficiary_address` show the individual's legal name and address.
* The account in `/accounts/{account_id}/automations` owns the Automation. `brand.account_id` selects the beneficiary identity, and `destination.address_id` selects the wallet receiving minted stablecoins. Branding does not change ownership, custody, or destination restrictions. Automations owned by transactional accounts must still target external destinations.

```json Request (business brand) theme={null}
{
  "name": "XYZ Onramp",
  "source": { "value_type": "USD" },
  "destination": {
    "address_id": "2MhCCIHulVdXrHiEuQDJvnKbSkl",
    "value_type": "SBC",
    "transfer_type": "solana"
  },
  "brand": { "account_id": "<BUSINESS_ACCOUNT_ID>" }
}
```

```json Request (individual brand) theme={null}
{
  "name": "Jane Doe Onramp",
  "source": { "value_type": "USD" },
  "destination": {
    "address_id": "2MhCCIHulVdXrHiEuQDJvnKbSkl",
    "value_type": "SBC",
    "transfer_type": "solana"
  },
  "brand": { "account_id": "<INDIVIDUAL_ACCOUNT_ID>" }
}
```

When the automation becomes active, `beneficiary_name` and `beneficiary_address` in `source.funding_instructions` reflect that account's verified identity — the business name and address for a business account, or the individual's legal name and address for an individual account. See [Individual accounts](https://docs.brale.xyz/guides/individual-accounts.md) for how to create an individual account whose identity can be used as a brand.

> [!NOTE]
>
> With testnet credentials, you can create branded Automations using a business or individual account you have access to, without completing mainnet KYB/KYC or enabling that account for mainnet. Testnet funding instructions contain placeholder banking details and cannot receive real deposits. See [Simulate a testnet deposit](#simulate-a-testnet-deposit) to fund one. Mainnet verification requirements are unchanged.

## Testnet Behavior

> [!NOTE]
>
> Automations created on testnet deployments are fully functional for testing purposes, but no real banking account is provisioned. Instead of live banking coordinates, Brale returns placeholder account details in `source.funding_instructions`. These placeholder coordinates cannot receive real deposits, and no actual funds movement occurs.
>
> For both branded and unbranded testnet Automations, `source.funding_instructions.account_number` contains the Automation's alphanumeric ID as a placeholder, not a numeric bank account number. This is expected.

### Simulate a testnet deposit

To fund a testnet Automation, call [Simulate an Automation deposit](https://docs.brale.xyz/api-reference/brale/simulate-automation-deposit.md). Brale creates a simulated inbound ACH, wire, or FedNow payment and runs the normal Automation mint path. Brale does not contact a bank, and no real fiat moves.

Requirements:

* Testnet API credentials with the `automations:write` and `network:testnet` scopes
* An Automation with `status: "active"`
* An Automation destination on a testnet chain, such as `base_sepolia` or `solana_devnet`

**POST** `https://api.brale.xyz/accounts/{account_id}/automations/{automation_id}/simulations/deposits`

```bash theme={null}
curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/automations/${AUTOMATION_ID}/simulations/deposits" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": { "value": "10.00", "currency": "USD" },
    "transfer_type": "wire"
  }'
```

`transfer_type` accepts `ach`, `wire`, or `fednow`. These are simulator inputs, not Transfer rail identifiers. A `fednow` simulation produces a Transfer with `source.transfer_type: "fednow_credit"`. Brale returns `202 Accepted` with the resulting [Transfer](https://docs.brale.xyz/key-concepts/transfers.md), including `automation_id`. `202` means the simulated deposit was accepted, not that the mint is complete.

After the simulated payment completes:

* Brale emits the normal `payment.completed` [webhook event](https://docs.brale.xyz/webhooks/webhook-events.md).
* Brale mints the stablecoin to the Automation's testnet destination.
* The Transfer moves through the normal statuses. Fetch it with `GET /accounts/{account_id}/transfers/{transfer_id}` and read `destination.transaction_id` for the testnet mint.

Use a new `Idempotency-Key` for each new simulated deposit. Retrying with the same key and body returns the original response without creating another payment, Transfer, or mint. See [Idempotency](https://docs.brale.xyz/key-concepts/idempotency.md).

## Listing Automations for a Customer

Retrieve all automations associated with a customer Account.

**GET** `https://api.brale.xyz/accounts/{account_id}/automations`

```json Response theme={null}
{
  "automations": [
    {
      "id": "35kVg1llbsOBYvx9XKr9eOtsD9z",
      "name": "Customer ABC Automation",
      "status": "active",
      "source": {
        "transfer_type": null,
        "value_type": "USD",
        "funding_instructions": {
          "bank_address": "123 Example St, Example City, NY 10001",
          "beneficiary_address": "456 Sandbox Ave, Suite 100, Example City, IA 50000",
          "beneficiary_name": "Example Payments Inc",
          "routing_number": "000111222",
          "account_number": "100123456789",
          "bank_name": "Example Bank",
          "memo": null
        }
      },
      "destination": {
        "transfer_type": "solana",
        "address_id": "35LWXNTO2jem13nXCLyciFdi162",
        "value_type": "ARB"
      },
      "updated_at": "2025-11-20T15:56:05.017508Z",
      "created_at": "2025-11-20T15:56:03.531196Z"
    },
    {
      "id": "35kVg1llbsOBYvx9XKr9eOtsD9z",
      "name": "Customer XYZ Automation",
      "status": "active",
      "source": {
        "transfer_type": null,
        "value_type": "USD",
        "funding_instructions": {
          "bank_address": "123 Example St, Example City, NY 10001",
          "beneficiary_address": "25 Main Ave, Suite 100, Example City, IA 50000",
          "beneficiary_name": "Company ABC",
          "routing_number": "000111222",
          "account_number": "000123456789",
          "bank_name": "Example Bank",
          "memo": null
        }
      },
      "destination": {
        "transfer_type": "solana",
        "address_id": "35LWXNTO2jem13nXCLyciFdi162",
        "value_type": "ARB"
      },
      "updated_at": "2025-11-20T15:56:05.017508Z",
      "created_at": "2025-11-20T15:56:03.531196Z"
    }
  ]
}
```

## Retrieve an Automation

Retrieve a specific Automation.

**GET** `https://api.brale.xyz/accounts/{account_id}/automations/{automation_id}`

```json Response theme={null}
{
  "id": "35kVg1llbsOBYvx9XKr9eOtsD9z",
  "name": "Customer XYZ Automation",
  "status": "active",
  "source": {
    "transfer_type": null,
    "value_type": "USD",
    "funding_instructions": {
      "bank_address": "123 Example St, Example City, NY 10001",
      "beneficiary_address": "25 Main Ave, Suite 100, Example City, IA 50000",
      "beneficiary_name": "Company ABC",
      "routing_number": "000111222",
      "account_number": "000123456789",
      "bank_name": "Example Bank",
      "memo": null
    }
  },
  "destination": {
    "transfer_type": "solana",
    "address_id": "35LWXNTO2jem13nXCLyciFdi162",
    "value_type": "ARB"
  },
  "updated_at": "2025-11-20T15:56:05.017508Z",
  "created_at": "2025-11-20T15:56:03.531196Z"
}
```

## Archive an Automation

Automations can be archived when they are no longer needed. Archiving permanently closes the automation's virtual account — no further deposits will be processed — and removes the Stripe billing seat for the automation.

> [!WARNING]
>
> Archived is a terminal state. An archived automation cannot be re-enabled.

**PATCH** `https://api.brale.xyz/accounts/{account_id}/automations/{automation_id}`

```json Request theme={null}
{
  "status": "archived"
}
```

```json Response theme={null}
{
  "id": "3D8pEQwvYY7cJXmQkojpZZ9vdr3",
  "name": "ACE Corp 5",
  "status": "archived",
  "source": {
    "transfer_type": null,
    "value_type": "USD",
    "funding_instructions": {
      "account_number": "488255579773",
      "beneficiary_name": "Brand Account 2",
      "bank_address": "8700 Perry Highway Pittsburgh, PA 15237",
      "beneficiary_address": "7834 pipe drive San Diego, CA 92115",
      "routing_number": "043087080",
      "bank_name": "SSB Bank"
    }
  },
  "destination": {
    "address_id": "3D8odPs57kcf4kErbi8snLOQg0H",
    "transfer_type": "base",
    "value_type": "ACE"
  },
  "updated_at": "2026-06-04T21:13:53.122105Z",
  "created_at": "2026-05-01T22:10:38.297457Z",
  "brand": {
    "account_id": "3D8occi363tmBYDByo0Rr292kBO"
  }
}
```

Required scope: `automations:write`