> ## 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.

# Transfer between wallets

> Move money instantly between two wallets

Move money instantly between two of your wallets. For the transfer lifecycle, read the [Transfers overview](/guides/concepts/transfers).

<Snippet file="shared/prerequisites.mdx" />

<Snippet file="shared/mcp-callout.mdx" />

<Snippet file="shared/cents-note.mdx" />

## Move funds

A transfer (`trf_*`) moves money between two wallets (`wal_*`) in the same party, landing in the same call; read `status` on the response. Create one with [`POST /transfers/internal`](/api-reference/transfers/initiate-internal-transfer). Internal transfers need more than one wallet on the party; see [Create and manage wallets](/guides/wallets/wallets). An agent can move money into the Vault but not out of it.

<Snippet file="shared/instance-id-note.mdx" />

<CodeGroup>
  ```python Python theme={null}
  import uuid
  from naturalpay import Natural

  client = Natural()
  transfer = client.transfers.initiate_internal(
      amount=5_000,
      source_wallet_id="wal_019cd1798d714ce765e0486a417c23dc",
      dest_wallet_id="wal_019cd1798d72cf01303c7c04148c9b8d",
      description="Sweep to Vault",
      idempotency_key=str(uuid.uuid4()),
  )
  print(transfer.data.id)
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  const client = new Natural();
  const transfer = await client.transfers.initiateInternal({
    amount: 5_000,
    sourceWalletId: "wal_019cd1798d714ce765e0486a417c23dc",
    destWalletId: "wal_019cd1798d72cf01303c7c04148c9b8d",
    description: "Sweep to Vault",
    idempotencyKey: crypto.randomUUID(),
  });
  console.log(transfer.data.id);
  ```

  ```bash CLI theme={null}
  natural transfers initiate-internal \
    --amount 5000 \
    --source-wallet-id wal_019cd1798d714ce765e0486a417c23dc \
    --dest-wallet-id wal_019cd1798d72cf01303c7c04148c9b8d \
    --description "Sweep to Vault" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Move $50 from my operating wallet to my Vault.
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/transfers/internal \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "amount": 5000,
          "sourceWalletId": "wal_019cd1798d714ce765e0486a417c23dc",
          "destWalletId": "wal_019cd1798d72cf01303c7c04148c9b8d",
          "description": "Sweep to Vault"
        }
      }
    }'
  ```
</CodeGroup>

The response carries the transfer (`trf_*`) and its `status`:

<Snippet file="api-examples/transfers.initiateInternal.response.mdx" />

A transfer moves `CREATED` to `PROCESSING` to `COMPLETED`. It can pause at `IN_REVIEW` during an approval hold. It ends at `FAILED`, `RETURNED`, `CANCELED`, or `APPROVAL_DENIED`.


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