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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Send domestic USD wires to external party accounts

<Note>
  Direct is in early access and subject to change. To request Direct access, contact [hi@natural.com](mailto:hi@natural.com).
</Note>

A wire (`wire_*`) sends USD from a [Wallet](/guides/concepts/wallets) to an [External party account](/guides/concepts/external-parties#external-party-accounts) over Fedwire.

| | |
| - | - |
| API | [Wire endpoints](/api-reference/wire/create-wire-payment) · [Errors](/api-reference/errors/wire) |
| Direction | Credit only (wallet → external account) |
| Currency | `USD`, domestic only |
| Settlement | Asynchronous and subject to bank processing; `expectedCompletionAt` is an estimate |
| Reversible | No — there is no `RETURNED` status, though the bank can reject a wire before completion (`REJECTED`) |
| Headers | `Idempotency-Key` required on create and cancel; `X-Instance-ID` for [agent](/guides/concepts/agents) calls |
| Alternatives | [ACH](/guides/concepts/ach) and [Realtime](/guides/concepts/realtime) |

## Create

```json theme={null}
{
  "data": {
    "attributes": {
      "amount": 250000,
      "externalPartyAccountId": "epa_019cd1798d8e5a2f8ceb96020cc3991a",
      "description": "Q3 vendor settlement",
      "remittanceInfo": "INV 1042"
    }
  }
}
```

* `description` is an internal label and is not sent to the bank. `remittanceInfo` is what the beneficiary sees. It is optional, up to 105 characters, and limited to letters, digits, spaces, and `/ - ? : ( ) . , ' +`. Your legal name and `remittanceInfo` together must fit in 140 characters.
* Fedwire requires a complete beneficiary address. If the [External party](/guides/concepts/external-parties) has none, create returns `400 wire.beneficiary_address_required`. Add the address with [`PATCH /external-parties/{externalPartyId}/address`](/api-reference/external-parties/correct-an-external-party-address), passing the party's current `addressVersion` as `expectedAddressVersion`, then retry the wire with the same IDs.
* The external party account's `supportedRails` is an advisory hint. The authoritative reachability check runs when you create the wire.
* To send on behalf of a customer, pass `customerPartyId`. See [Move money for a customer](/guides/connect/move-money-for-customer).

## Lifecycle

| Status | Meaning | Terminal | Sets |
| - | - | - | - |
| `CREATED` | Accepted and waiting to be submitted | No | |
| `AWAITING_APPROVAL` | Held for [approval](/guides/concepts/approvals) after breaching a [limit](/guides/concepts/limits) | No | |
| `PROCESSING` | Submitted to the bank | No | `submittedAt` |
| `COMPLETED` | Settled by the receiving bank | Yes | `completedAt`, `terminalAt` |
| `REJECTED` | Rejected by the bank; details in `failure` | Yes | `rejectedAt`, `terminalAt` |
| `APPROVAL_DENIED` | Approval was denied | Yes | `terminalAt` |
| `FAILED` | Failed before or during processing; details in `failure` | Yes | `terminalAt` |
| `CANCELED` | Canceled through the API | Yes | `terminalAt` |

**Cancel** — A wire can be canceled while it is `CREATED` or `AWAITING_APPROVAL`. Once submission starts, cancel returns `400 wire.not_cancellable`. Canceling emits no `wire.*` event.

**Events** — Status changes emit `wire.created`, `wire.processing`, `wire.completed`, `wire.rejected`, and `wire.failed`. Approval holds emit `approval.*` events instead. Events go to your webhooks, and to a connected customer's webhooks when they have granted Direct read access. The fee is assessed when the wire is submitted, so it's always null on `wire.created`. Read it from `wire.processing`. Payloads are documented in the [event catalog](/api-reference/event-catalog).

**Sandbox** — Drive a test wire to a terminal state without waiting on the bank: [settle](/api-reference/simulations/settle-wire) moves it to `COMPLETED` and [fail](/api-reference/simulations/fail-wire) moves it to `REJECTED`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.