> ## 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. # Create a new transfer > Creates a new transfer using the specified source and destination details. Use the playground below to try this endpoint directly, or review the OpenAPI details in the right panel. ## OpenAPI ````yaml POST /accounts/{account_id}/transfers openapi: 3.0.3 info: title: Brale Issuance and Orchestration 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: Accounts description: Endpoints related to managing customer accounts (KYB, details, etc.) - name: Transfers description: >- Endpoints for creating and retrieving transfers (fiat to stablecoins, etc.) - name: Addresses description: >- On-chain and off-chain endpoints (custodial or external) represented by a single Addresses resource - name: Financial Institutions description: Legacy (deprecated) bank endpoints. Use Addresses instead. - name: Automations description: Automated deposit addresses or onramps - name: Plaid description: Bank linking and ACH debit via Plaid. - name: Orders description: Legacy tag used for transfers in older specs. paths: /accounts/{account_id}/transfers: post: tags: - Transfers - Orders summary: Create a new transfer description: >- Creates a new transfer using the specified source and destination details. operationId: createTransfer parameters: - name: account_id in: path required: true description: The ID of the account schema: $ref: '#/components/schemas/Ksuid' - 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/CreateTransfer' examples: ach_debit_to_solana: summary: Onramp via ACH debit → Mint on Solana value: amount: value: '2500.00' currency: USD source: address_id: 2VcUIonJeVQzFoBuC7LdFT0dRe4 value_type: USD transfer_type: ach_debit destination: address_id: 35LWXNTO2jem13nXCLyciFdi162 value_type: SBC transfer_type: solana wire_offramp_with_brand: summary: Burn on Polygon → Wire out (brand override) value: amount: value: '10000.00' currency: USD source: address_id: 35LWXNTO2jem13nXCLyciFdi162 value_type: SBC transfer_type: polygon destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: USD transfer_type: wire wire_memo: Invoice 1048 brand: account_id: 2VcUIIsgARwVbEGlIYbhg6fGG57 rtp_payout: summary: Stablecoin payout via RTP value: amount: value: '150.00' currency: USD source: address_id: 35LWXNTO2jem13nXCLyciFdi162 value_type: SBC transfer_type: ethereum destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: USD transfer_type: rtp_credit fednow_payout: summary: Stablecoin payout via FedNow description: >- Pays out USD over FedNow from a funded Brale internal Address. The source `value_type` and `transfer_type` must match the token and network held by the source Address. The destination bank Address must be `active` and list `fednow_credit` in `transfer_types`. value: amount: value: '1.00' currency: USD source: address_id: 2VcUIonJeVQzFoBuC7LdFT0dRe4 value_type: USDB transfer_type: spark destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: USD transfer_type: fednow_credit responses: '201': description: >- Transfer successfully created. Creation is not settlement. Track `status` until it reaches `complete`, `canceled`, or `failed`. content: '*/*': schema: $ref: '#/components/schemas/Transfer' '422': description: > The request is valid but cannot be processed. Known cases include `insufficient_balance` (the source Address does not hold enough of the source `value_type`) and reuse of an `Idempotency-Key` with a different body or URI. After funding the source Address, retry `insufficient_balance` with the same `Idempotency-Key` and body. For an `ach_debit` transfer, Brale can also reject the request when the source bank Address cannot be debited: - `bank_account_not_linked`: the bank account is not linked through Plaid. Link the bank account before using it for an ACH debit. - `bank_account_relink_required`: the bank account's Plaid link has expired. Have the user relink the bank account, then retry. - `bank_balance_unavailable`: Brale could not verify the bank account's balance. Retry, or relink the bank account if the error continues. - `insufficient_balance`: the transfer amount exceeds the bank account's available balance. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' components: schemas: Ksuid: title: Kusid type: string format: ksuid pattern: ^[a-zA-Z0-9]{27}$ example: 2VcUIIsgARwVbEGlIYbhg6fGG57 CreateTransfer: type: object additionalProperties: false required: - amount - source - destination properties: amount: $ref: '#/components/schemas/Amount' source: $ref: '#/components/schemas/PaymentData' destination: $ref: '#/components/schemas/PaymentData' brand: $ref: '#/components/schemas/BrandData' note: type: string title: CreateTransfer 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 - refunding - refunded example: pending failure: allOf: - $ref: '#/components/schemas/TransferFailure' nullable: true 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 nullable: true 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. nullable: true 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' 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 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 PaymentData: type: object additionalProperties: false title: PaymentData properties: address_id: type: string description: Preferred Address identifier financial_institution_id: type: string deprecated: true description: Legacy—use address_id transfer_type: type: string value_type: type: string wire_memo: type: string description: >- Optional memo or payment reference text sent with outbound wire transfers. Only applies when transfer_type is wire. required: - transfer_type - value_type BrandData: type: object nullable: true additionalProperties: false required: - account_id properties: account_id: type: string 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 nullable: true 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 nullable: true 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 nullable: true description: Human-readable return reason, when available. example: Account closed 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 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 and ACH 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 format: date-time nullable: true description: When the underlying payment was received or posted. example: '2026-04-07T00:01:24.514000Z' sender_name: type: string nullable: true description: Name of the originating sender, when available. example: Originator Name sender_bank_name: type: string nullable: true description: Originating bank name, when available. example: JPMorgan Chase Bank sender_bank_routing_number: type: string nullable: true description: Originating bank routing number, when available. example: '000000123' payment_reference: type: string nullable: true 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 nullable: true description: Wire IMAD / tracking identifier, when available. example: 20260406XOIZJDPP953495 trace_number: type: string nullable: true description: >- ACH trace identifier for the underlying payment, when available. Appears on `source.payment_details` for inbound ACH-funded transfers and on `destination.payment_details` for outbound ACH transfers (`ach_credit` and `same_day_ach_credit`) once the trace number is assigned. example: '021000029876543' sent_at: type: string format: date-time nullable: true description: >- When the outbound payment was sent, when available. Appears on `destination.payment_details` for outbound wire and ACH transfers. example: '2026-04-07T00:04:58.000000Z' 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 " header. ````