Brale Automations API

openapi: 3.2.0
info:
  title: Brale Issuance and Orchestration Automations API
  version: 2.3.1
  description: 'Brale supports stablecoin issuance and orchestration, enabling businesses and

    ecosystems to create their own stablecoins and convert between fiat and stablecoins

    seamlessly. From stablecoin onramps, offramps, and swaps to custody and payouts, the

    Brale API makes it easy to build stablecoin-enabled products.


    NOTE: All resource IDs (including account_id, address_id, financial_institution_id,

    and automation_id) are KSUIDs—27-character alphanumeric strings that are sortable

    by time. Examples showing UUIDs are incorrect.


    **What''s new in 2.3.1**

    - Unified **Addresses** model for on-chain and off-chain endpoints

    - `Transfers` now accepts **address_id only** (no financial_institution_id)

    - Optional `brand` object to control bank statement presentation (`branding` still accepted as legacy alias)

    - Added off-chain rails: `ach_credit`, `same_day_ach_credit`, `ach_debit`, `same_day_ach_debit`, `rtp-credit`

    - Plaid endpoints moved to `/accounts/{account_id}/plaid/*`

    - `Financial Institutions` marked **deprecated** (migration path to **Addresses**)

    - Create Account now uses `CreateManagedAccountRequest` with `beneficial_owners`, `business_controller`, and `EndUserTosAttestation`.

    - Transfers now accept `brand` (replaces `branding`, still aliased in docs).

    - Plaid endpoints updated to return `address_id` and accept `transfer_types`.

    - Off-chain Address creation uses `CreateExternalAddressRequest` oneOf with bank + blockchain variants.

    - FI endpoints kept but marked deprecated; use Addresses instead.

    - `rtp_credit` is the canonical RTP rail name.


    **FedNow**

    - Added the `fednow_credit` rail. Outbound: create a Transfer with

    `destination.transfer_type: fednow_credit` to a bank Address that lists

    `fednow_credit` in `transfer_types`. Inbound: payers send FedNow credits to an

    active Automation''s `source.funding_instructions`; Brale creates the Transfer

    automatically with `source.transfer_type: fednow_credit`.

    - Simulate a testnet FedNow deposit with `transfer_type: fednow` on

    `POST /accounts/{account_id}/automations/{automation_id}/simulations/deposits`.

    - `bank_address` and `beneficiary_address` are required only when an external

    bank Address requests `wire`.

    - FedNow availability depends on account enablement.'
servers:
- url: https://api.brale.xyz
  description: Production server
security:
- BearerAuth: []
tags:
- name: Automations
  description: Automated deposit addresses or onramps
paths:
  /accounts/{account_id}/automations:
    post:
      tags:
      - Automations
      operationId: createAutomations
      summary: Create an Automation
      description: Creates a new automation.
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Ksuid'
        description: The ID of the account
      - in: header
        name: Idempotency-Key
        required: true
        schema:
          type: string
        example: idemp-123e4567-e89b-12d3-a456-426614174000
        description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000`

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationCreateRequest'
      responses:
        '201':
          description: Automation successfully created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Automation'
    get:
      tags:
      - Automations
      operationId: listAutomations
      summary: Fetch all automations for an account
      description: Retrieves all automations associated with the specified customer account.
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Ksuid'
        description: The ID of the account
      responses:
        '200':
          description: A list of automations
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GetAutomationsResponse'
  /accounts/{account_id}/automations/{id}:
    get:
      tags:
      - Automations
      operationId: getAutomations
      summary: Retrieve a single automation
      description: Returns details for a specific automation.
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Ksuid'
        description: The ID of the account
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Ksuid'
        description: The ID of the automation
      responses:
        '200':
          description: A single automation object
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Automation'
  /accounts/{account_id}/automations/{automation_id}/simulations/deposits:
    post:
      tags:
      - Automations
      operationId: simulate_automation_deposit
      summary: Simulate Automation Deposit
      description: 'Simulates an inbound ACH, wire, or FedNow deposit into a testnet Automation and runs the normal Automation mint path. Returns the resulting Transfer. The request `transfer_type` is a simulator input (`ach`, `wire`, or `fednow`). A `fednow` simulation produces a Transfer with `source.transfer_type: fednow_credit`.


        Available only with testnet credentials. Required scopes: `automations:write` and `network:testnet`.


        The Automation must belong to the account in the path, be `active`, and have a testnet destination chain. Brale does not contact a bank and no real fiat moves.


        Retrying with the same `Idempotency-Key` and body returns the original `202` response without creating another payment, Transfer, or mint.'
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Ksuid'
        description: The ID of the account that owns the Automation
      - name: automation_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Ksuid'
        description: The ID of the testnet Automation to fund
      - in: header
        name: Idempotency-Key
        required: true
        schema:
          type: string
        example: idemp-123e4567-e89b-12d3-a456-426614174000
        description: 'A unique string used to prevent duplicate operations. Use a new key for each new simulated deposit. Reuse the same key only to retry the same request. Reusing a key with a different body or URI returns `422`.

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateAutomationDepositRequest'
            examples:
              fednow:
                summary: Simulate a FedNow deposit
                value:
                  amount:
                    value: '1.00'
                    currency: USD
                  transfer_type: fednow
              wire:
                summary: Simulate a wire deposit
                value:
                  amount:
                    value: '10.00'
                    currency: USD
                  transfer_type: wire
              ach:
                summary: Simulate an ACH deposit
                value:
                  amount:
                    value: '10.00'
                    currency: USD
                  transfer_type: ach
      responses:
        '202':
          description: Accepted. Returns the Transfer created by the Automation. The Transfer includes `automation_id`, and `source.transfer_type` identifies the simulated rail. For `fednow`, `source.transfer_type` is `fednow_credit`. `202` means the simulated deposit was accepted. It does not mean the mint is complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '400':
          description: "Invalid request or schema. Known cases:\n\n- `transfer_type` is not `ach`, `wire`, or `fednow` (for example,\n  `rtp` or `fednow_credit`) — schema validation error.\n\n- `invalid_currency` — the currency is not a supported reserve\n  currency (for example, `EUR`).\n\n- `invalid_amount` — the amount is malformed, zero, or negative. For\n  zero, `detail` is `Amount must be greater than zero`.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorV2'
        '401':
          description: Unauthorized. Missing or invalid bearer token.
        '403':
          description: Forbidden. The credentials do not include `network:testnet` or another required scope. Mainnet API keys receive this response.
        '404':
          description: The account or Automation was not found, or the Automation does not belong to the account in the path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorV2'
        '422':
          description: "The request is valid but cannot be processed. Known cases:\n\n- `mainnet_destination` — `Deposit simulation is only available for\n  testnet automations`.\n\n- `automation_not_active` — `Automation must be active to simulate a\n  deposit`. Returned for pending, disabled, archived, or otherwise\n  inactive Automations.\n\n- The `Idempotency-Key` was already used with a different request body\n  or URI.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorV2'
components:
  schemas:
    PaymentDetails:
      title: PaymentDetails
      type: object
      description: Underlying payment metadata for a transfer leg. Response-only. Appears on `source.payment_details` for inbound fiat-funded transfers (wire, ACH, and FedNow) and on `destination.payment_details` for outbound wire transfers. Optional and may be absent depending on the rail and on whether the underlying bank metadata is available yet. Fields are rail-specific. For example, `imad` applies only to wires and `trace_number` only to ACH. Do not expect wire or ACH identifiers on `fednow_credit` legs.
      properties:
        received_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the underlying payment was received or posted.
          example: '2026-04-07T00:01:24.514000Z'
        sender_name:
          type:
          - string
          - 'null'
          description: Name of the originating sender, when available.
          example: Originator Name
        sender_bank_name:
          type:
          - string
          - 'null'
          description: Originating bank name, when available.
          example: JPMorgan Chase Bank
        sender_bank_routing_number:
          type:
          - string
          - 'null'
          description: Originating bank routing number, when available.
          example: '000000123'
        payment_reference:
          type:
          - string
          - 'null'
          description: Sender-provided payment reference or memo, when available. For inbound wires, Brale may also populate this field from "Instruction for Creditor Agent," which some banks label "Message to receiving bank." This fallback is used only when no existing memo, Originator-to-Beneficiary Information (OBI), or remittance reference is available. Existing reference precedence is preserved.
          example: Simulated Wire
        imad:
          type:
          - string
          - 'null'
          description: Wire IMAD / tracking identifier, when available.
          example: 20260406XOIZJDPP953495
        trace_number:
          type:
          - string
          - 'null'
          description: ACH trace identifier for the underlying payment, when available. Primarily relevant for inbound ACH-funded transfers.
          example: 021000029876543
    TransferEndpoint:
      title: TransferEndpoint
      description: One side (source or destination) of a Transfer. The same shape is used in create requests and in responses. Response-only fields like `transaction_id` and `payment_details` are populated by Brale as the underlying leg settles.
      type: object
      properties:
        value_type:
          type: string
          example: USD
        transfer_type:
          type: string
          example: wire
        address_id:
          $ref: '#/components/schemas/Ksuid'
        financial_institution_id:
          type: string
          deprecated: true
          description: Legacy — use `address_id`.
        wire_memo:
          type: string
          description: Optional memo or payment reference text sent with outbound wire transfers. Only applies when `transfer_type` is `wire` on the destination leg.
        transaction_id:
          type: string
          description: On-chain transaction hash or off-chain payment reference. Present in responses once the leg has been submitted to the network. Not included in create requests.
          example: 0xdd5646ea…
        payment_details:
          $ref: '#/components/schemas/PaymentDetails'
      required:
      - value_type
      - transfer_type
    AutomationBrand:
      title: AutomationBrand
      type: object
      description: Optional. Selects the verified identity shown as the beneficiary on the automation's funding instructions. Pass the account_id of your own account or a managed account (business or individual). The automation is still created under the account in the request path; `brand.account_id` only controls the identity rendered on the funding instructions. If omitted, Brale is the default beneficiary.
      properties:
        account_id:
          $ref: '#/components/schemas/Ksuid'
          description: The account whose verified identity appears as the beneficiary on wire and ACH funding instructions. For a business account, this is the business name and address. For an individual account, this is the individual's legal name and address.
      required:
      - account_id
    Automation:
      title: Automation
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Ksuid'
        name:
          type: string
          example: XYZ Onramp
        status:
          type: string
          description: The current lifecycle state of the automation.
          enum:
          - pending
          - active
          - disabled
          - archived
          example: active
        source:
          $ref: '#/components/schemas/AutomationSource'
        destination:
          $ref: '#/components/schemas/AutomationDestination'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T12:34:56Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T12:34:56Z'
        brand:
          $ref: '#/components/schemas/AutomationBrand'
    FundingInstructions:
      title: FundingInstructions
      type: object
      description: Bank details for the virtual account that funds the automation. Populated by Brale once the automation becomes active. Share these coordinates with the payer to fund the automation.
      properties:
        beneficiary_name:
          type: string
          example: Jane Business
        bank_name:
          type: string
          example: Example Bank
        bank_address:
          type: string
          example: 456 Commerce St., Des Moines, IA 50309
        beneficiary_address:
          type: string
          example: 612 Commerce St., Des Moines, IA 50309
        account_number:
          type: string
          example: '123456789'
        routing_number:
          type: string
          example: 063108680
    SimulateAutomationDepositRequest:
      title: SimulateAutomationDepositRequest
      type: object
      description: Request body for simulating an inbound fiat deposit into a testnet Automation.
      additionalProperties: false
      properties:
        amount:
          allOf:
          - $ref: '#/components/schemas/Amount'
          description: Deposit amount. `value` must be a positive decimal string greater than zero. `currency` must be a reserve currency accepted by the API.
          example:
            value: '10.00'
            currency: USD
        transfer_type:
          type: string
          description: 'Inbound rail to simulate. This is a simulator input, not a Transfer rail identifier. `fednow` produces a Transfer with `source.transfer_type: fednow_credit`.'
          enum:
          - ach
          - wire
          - fednow
          example: fednow
      required:
      - amount
      - transfer_type
    GetAutomationsResponse:
      title: AutomationListResponse
      type: object
      properties:
        automations:
          type: array
          items:
            $ref: '#/components/schemas/Automation'
    Transfer:
      title: Transfer
      type: object
      description: A money movement between a source and a destination. Returned by the create, get, and list transfer endpoints. The same shape is used everywhere a Transfer is exposed to API consumers.
      properties:
        id:
          $ref: '#/components/schemas/Ksuid'
        status:
          type: string
          description: Lifecycle stage of the transfer
          enum:
          - pending
          - processing
          - complete
          - canceled
          - failed
          example: pending
        failure:
          allOf:
          - $ref: '#/components/schemas/TransferFailure'
          description: Structured failure details for a failed transfer. Usually `null`. Populated when `status` is `failed` and Brale has structured failure details for the transfer — most commonly for ACH returns, outbound wire returns, and other rail/provider failures. Clients should not assume `failure` is always present for every failed transfer; check for `null` before reading nested fields.
          example: null
        source:
          $ref: '#/components/schemas/TransferEndpoint'
        destination:
          $ref: '#/components/schemas/TransferEndpoint'
        amount:
          $ref: '#/components/schemas/Amount'
        note:
          type:
          - string
          - 'null'
          description: Optional free-form note attached to the transfer.
          example: null
        automation_id:
          allOf:
          - $ref: '#/components/schemas/Ksuid'
          description: ID of the Automation that created this transfer, when applicable. Omitted for transfers created directly via the API.
        funding_simulated:
          type: boolean
          description: Optional. When returned with a value of `true`, the source funding for this transfer was simulated in testnet rather than coming from a real payment. Not every simulated transfer is guaranteed to include this field. Not present for production-funded transfers.
        created_at:
          type: string
          format: date-time
          example: '2026-01-01T00:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-01T00:00:00Z'
    TransferFailure:
      title: TransferFailure
      type: object
      description: Structured failure details for a failed transfer. Populated by Brale when `status` is `failed` and the underlying rail/provider has supplied structured failure details. Field availability varies by rail — for example, `ach_return` is only present for ACH returns and `wire_return` is only present for outbound wire returns. Do not require rail-specific fields for other failure types.
      properties:
        type:
          type: string
          description: Error classification for the failure, for example `ach_return` or `wire_return`.
          example: ach_return
        occurred_at:
          type: string
          format: date-time
          description: When Brale recorded the failure. This is not necessarily the exact time the bank returned the payment.
          example: '2026-04-07T00:05:12.102000Z'
        retriable:
          type: boolean
          description: Whether the failure is considered retriable. When `true`, Brale may automatically retry the underlying operation; when `false`, the failure is permanent.
          example: false
        ach_return:
          type:
          - object
          - 'null'
          description: ACH-only return details. Present for ACH return failures; `null` or not set for wire returns, on-chain failures, and other rail failures.
          properties:
            code:
              type: string
              description: ACH return code (e.g. `R01` — Insufficient Funds).
              example: R01
            reason:
              type: string
              description: Human-readable description of the ACH return reason.
              example: Insufficient Funds
            category:
              type: string
              description: Simplified taxonomy of the ACH return. `administrative` covers bank issues that may be retriable. `unauthorized` covers customer disputes. `general` covers everything else.
              enum:
              - administrative
              - unauthorized
              - general
              example: administrative
        wire_return:
          type:
          - object
          - 'null'
          description: Wire-only return details. Present when `type` is `wire_return` for a returned outbound wire; `null` or not set for other failures. Has no `category` field; the ACH return taxonomy does not apply.
          properties:
            code:
              type: string
              description: The provider's wire return reason code when available (for example, `AC04`). When the provider supplies no code, Brale sets `WIRE_RETURN`, a Brale fallback marker that is not an ISO 20022 bank reason code.
              example: AC04
            reason:
              type:
              - string
              - 'null'
              description: Human-readable return reason, when available.
              example: Account closed
    AutomationCreateRequest:
      title: AutomationCreateRequest
      type: object
      properties:
        name:
          type: string
          example: XYZ Onramp
        source:
          $ref: '#/components/schemas/AutomationSource'
        destination:
          $ref: '#/components/schemas/AutomationDestination'
        brand:
          $ref: '#/components/schemas/AutomationBrand'
      required:
      - name
      - source
      - destination
    AutomationSource:
      title: AutomationSource
      type: object
      description: 'The funding source for the automation. Set `value_type: USD` to accept fiat deposits. You do not need to select a deposit rail: a USD Automation''s virtual account accepts the inbound rails enabled for your account (wire, ACH, and FedNow where enabled). When the automation becomes active, `funding_instructions` is populated with the virtual account details to share with the payer. This is Automation configuration. The rail of each deposit is reported on the resulting Transfer''s `source.transfer_type` (for example, `fednow_credit`), not here.'
      properties:
        value_type:
          type: string
          description: The fiat value type accepted by the automation (e.g. `USD`).
          example: USD
        transfer_type:
          type:
          - string
          - 'null'
          description: Optional. Omit this field to accept every inbound rail enabled for the virtual account. Responses may return `null`. Do not set it to restrict deposits to FedNow. A null value does not mean FedNow is unavailable.
          example: null
        funding_instructions:
          $ref: '#/components/schemas/FundingInstructions'
      required:
      - value_type
    Amount:
      title: Amount
      type: object
      description: Monetary value with explicit currency
      additionalProperties: false
      properties:
        value:
          type: string
          example: '11234.88'
        currency:
          type: string
          example: USD
      required:
      - value
      - currency
    ApiErrorV2:
      title: ApiErrorV2
      type: object
      description: Error envelope returned by newer Brale endpoints.
      required:
      - type
      properties:
        type:
          type: string
          description: Machine-readable error type identifier.
          example: automation_not_active
        detail:
          type: string
          description: Human-readable explanation of the error.
          example: Automation must be active to simulate a deposit
        code:
          type: string
          example: ValidationError
        status:
          type: integer
          example: 422
        values:
          type: array
          items:
            type: string
    AutomationDestination:
      title: AutomationDestination
      type: object
      description: The destination wallet that receives minted stablecoins when the automation is funded.
      properties:
        address_id:
          $ref: '#/components/schemas/Ksuid'
        value_type:
          type: string
          description: The stablecoin value type minted to the destination (e.g. `SBC`).
          example: SBC
        transfer_type:
          type: string
          description: The destination chain or rail (e.g. `solana`).
          example: solana
      required:
      - address_id
      - value_type
      - transfer_type
    Ksuid:
      title: Kusid
      type: string
      format: ksuid
      pattern: ^[a-zA-Z0-9]{27}$
      example: 2VcUIIsgARwVbEGlIYbhg6fGG57
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use the Bearer token returned from the Auth endpoint via OAuth2 client_credentials flow. Include the token in the "Authorization: Bearer <token>" header.

        '
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.brale.xyz/oauth2/token
          scopes:
            accounts:read: Read account details
            accounts:write: Create or update accounts
            addresses:read: Read address details
            addresses:write: Create addresses
            automations:read: Read automations
            automations:write: Create automations
            network:testnet: Access testnet-only operations, such as Automation deposit simulation
            financial-institutions:read: Read FI details (legacy)
            financial-institutions:write: Create FI (legacy)
            transfers:read: Read transfers
            transfers:write: Create transfers
x-tagGroups:
- name: Core
  tags:
  - Accounts
  - Addresses
  - Transfers
  - Automations
  - Plaid
- name: Legacy
  tags:
  - Financial Institutions
  - Orders
x-provenance:
  method: harvested
  publisher: Brale
  source: https://docs.brale.xyz/api-reference/brale-openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)