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

# Edit Wallet

> Update the configuration of an existing Finrock wallet: freeze or unfreeze it, and set or unset auto-forwarding of incoming funds to an address.

**[MCP scope](https://apidocs.finrock.io/api-reference/mcp-scopes.md):** `dac.funds` (not available to AI connectors yet)

Use this endpoint to freeze or unfreeze an existing wallet, or to set or update its auto-forwarding. Identify the wallet by its `asset`, then pass `is_frozen` to change its frozen state, a `forwarding` object to configure auto-forwarding, or both.

## Auto-forwarding

Auto-forwarding sends funds from your wallet to an external address automatically, so you don't have to submit withdrawals yourself. When a wallet has auto-forwarding set up, Finrock forwards incoming funds to the `forwarding.address` you provide. With `RealTime` frequency, funds are forwarded as soon as they are added to the wallet. With `Nightly` (the default), they are batched and forwarded once per night.

The destination must be an external address. Forwarding to an address that belongs to your own Finrock account returns HTTP `400` with `{"code": 1100, "error": "INTERNAL_DESTINATION_NOT_ALLOWED"}`.

A new forwarding address doesn't take effect straight away. The response shows `forwarding.status` as `PENDING_OWNER_APPROVAL` until the owner, or at least 2 admins, approve it in the dashboard.

To turn off auto-forwarding, send `"forwarding": { "address": null }`. To cancel a forwarding address that's still waiting for approval, send `"forwarding": { "address": "" }`. Sending `"forwarding": null`, or leaving `forwarding` out, leaves the current forwarding unchanged.

Common uses include:

* Sweeping customer deposits into a cold wallet or treasury account
* Settling received funds straight to an exchange account
* Keeping balances in hot wallets as low as possible

> [!WARNING]
>
> Forwarded funds are sent on-chain and can't be reversed. Validate the destination address with [Validate Address](https://apidocs.finrock.io/api-reference/wallets/validate-address.md) before you set it.

## Body Parameters

**asset** `string` *required*

The asset of the wallet to update. Use the `id` value from the [Supported Assets](https://apidocs.finrock.io/api-reference/utilities/supported-assets.md) list (e.g. `ETH`, `BTC`, `TRX_TEST`).

**is\_frozen** `boolean`

Set to `true` to freeze the wallet, or `false` to make it active. Send `null` or leave this field out to keep the current state. In the dashboard, the **Freeze Wallet** toggle under **Settings → Sub Accounts → Manage** does the same.

**requires\_dt\_memo** `object`

XRP wallets only. Makes the XRP Ledger reject any deposit to this wallet that doesn't include a destination tag. Use this when you share one XRP address across customers and rely on destination tags to credit the right one. Send `null` or leave this field out to keep the current setting.

A change takes effect once the owner, or at least 2 admins, approve it in the dashboard. Until then, `requires_dt_memo.change` in the response is `PENDING_OWNER_APPROVAL`.

**properties**

**enabled** `boolean` (default: false)

Set to `true` to reject deposits without a destination tag, or `false` to accept them.

**forwarding** `object`

Auto-forwarding settings for the wallet. To turn off auto-forwarding, send `{ "address": null }`. Sending `null`, or leaving this field out, leaves the current forwarding unchanged.

**properties**

**address** `string`

The external destination address that receives forwarded funds. Check it with [Validate Address](https://apidocs.finrock.io/api-reference/wallets/validate-address.md) before setting it.

**frequency** `string` (default: Nightly)

How often funds are forwarded to the destination address.

| Value | Behavior |
| - | - |
| `Nightly` | Batches received funds and forwards them once per night. This is the default. |
| `RealTime` | Forwards funds as soon as they are added to the wallet. |

```bash cURL theme={null}
curl --request PATCH \
     --url https://api.finrock.io/dac/v1/wallet \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "asset": "TRX_TEST",
       "forwarding": {
         "address": "TQPuRFi4E9jERdPXae4FE7SdWFJjJ6NUdd",
         "frequency": "Nightly"
       }
     }'
```

```bash Require destination tag (XRP) theme={null}
curl --request PATCH \
     --url https://api.finrock.io/dac/v1/wallet \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "asset": "XRP",
       "requires_dt_memo": {
         "enabled": true
       }
     }'
```

```bash Unset forwarding theme={null}
curl --request PATCH \
     --url https://api.finrock.io/dac/v1/wallet \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "asset": "TRX_TEST",
       "forwarding": {
         "address": null
       }
     }'
```

## Response

A successful request returns HTTP `200` with the updated wallet object.

**asset** `string`

The asset name of the wallet (e.g. `BTC`).

**asset\_ticker** `string`

The ticker symbol of the asset (e.g. `BTC`).

**is\_frozen** `boolean`

Whether the wallet is frozen.

**balance** `object`

The wallet's balances, in the asset's native unit.

**properties**

**available** `number`

Balance available to spend.

**unconfirmed** `number`

Balance from incoming transactions that are not yet confirmed on-chain.

**frozen** `number`

Amount of the balance that is currently frozen.

**forwarding** `object`

Auto-forwarding configuration for the wallet after the update.

**properties**

**status** `string`

Auto-forwarding status:

| Value | Meaning |
| - | - |
| `NONE` | Auto-forwarding isn't set up. |
| `PENDING_OWNER_APPROVAL` | A new forwarding address is waiting for the owner, or at least 2 admins, to approve it in the dashboard. Funds aren't forwarded yet. |
| `ACTIVE` | Auto-forwarding is active. |

**address** `string | null`

Destination address funds are forwarded to, or `null` if not set.

**frequency** `string`

How often funds are forwarded: `Nightly` or `RealTime`.

**wallet\_type** `string`

The type of wallet: `Legacy`, `HSM` or `MPC`. See [Wallet Types](https://apidocs.finrock.io/concepts/wallet-types.md).

**status** `string`

The wallet's status: `Creating` while it's being set up, `Created` when it's ready, or `Failed`.

**requires\_dt\_memo** `object`

XRP wallets only. Whether the XRP Ledger rejects deposits to this wallet that don't include a destination tag.

**properties**

**enabled** `boolean`

`true` if deposits without a destination tag are rejected. While a change is pending, this already shows the new value; check `change` to see whether it has been approved.

**change** `string`

State of the latest change to this setting: `APPROVED`, or `PENDING_OWNER_APPROVAL` while it waits for the owner, or at least 2 admins, to approve it in the dashboard.

```json 200 theme={null}
{
  "asset": "BTC",
  "asset_ticker": "BTC",
  "is_frozen": false,
  "balance": {
    "available": 0.025,
    "unconfirmed": 0.001,
    "frozen": 0.005
  },
  "forwarding": {
    "status": "ACTIVE",
    "address": "bc1qexample123456789",
    "frequency": "Nightly"
  },
  "wallet_type": "Legacy",
  "status": "Created",
  "requires_dt_memo": {
    "enabled": true,
    "change": "PENDING_OWNER_APPROVAL"
  }
}
```


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