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

# POST /dac/v1/auto-forwarding — Configure Auto-Forwarding

> Configure automatic forwarding of all incoming asset deposits to an external address. Choose Nightly batch forwarding or RealTime per-deposit forwarding.

The Auto-Forwarding endpoint configures your sub-account to automatically send received funds for a given asset to a designated external address. This is commonly used to sweep collected deposits into a cold wallet, treasury account, or exchange account without manual intervention. You choose the forwarding frequency: `Nightly` batches and forwards all accumulated funds once per day, while `RealTime` forwards each incoming deposit as soon as it is confirmed on-chain.

## Request

<ParamField header="x-api-key" type="string" required>
  Your Finrock API key.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your JWT bearer token in the format `Bearer {JWT}`.
</ParamField>

<ParamField body="asset" type="string" required>
  The asset ticker for which to configure auto-forwarding (e.g. `BTC`, `ETH`). Use the `asset_name` value from the [Supported Assets](/api-reference/utilities/supported-assets) list.
</ParamField>

<ParamField body="address" type="string" required>
  The external destination address to which all incoming funds will be forwarded. Validate this address using [Validate Address](/api-reference/wallets/validate-address) before setting it here.
</ParamField>

<ParamField body="frequency" type="string" default="Nightly">
  Controls how soon after receipt funds are forwarded to the destination address.

  | Value      | Behaviour                                                                                                               |
  | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
  | `Nightly`  | Batches all received funds and forwards them once per night in a single transaction. Lower gas cost per unit forwarded. |
  | `RealTime` | Forwards funds immediately after each confirmed deposit. Minimises settlement latency.                                  |

  Allowed values: `Nightly`, `RealTime`
</ParamField>

## Example Request

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

## Response

A successful request returns HTTP `200` confirming that auto-forwarding has been configured.

<ResponseField name="asset" type="string">
  The asset for which auto-forwarding is now active.
</ResponseField>

<ResponseField name="address" type="string">
  The external destination address that will receive forwarded funds.
</ResponseField>

<ResponseField name="frequency" type="string">
  The configured forwarding frequency (`Nightly` or `RealTime`).
</ResponseField>

<ResponseField name="status" type="string">
  Configuration status. Typical value: `active`.
</ResponseField>

```json Sample 200 Response theme={null}
{
  "asset": "BTC",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "frequency": "Nightly",
  "status": "active"
}
```

<ResponseField name="400" type="object">
  Returned when a required field is missing, the address is invalid, or the asset does not support auto-forwarding.
</ResponseField>

```json Sample 400 Response theme={null}
{
  "error": "Bad Request",
  "message": "The destination address failed validation for asset BTC."
}
```

<Note>
  Updating the auto-forwarding configuration by calling this endpoint again with a different address or frequency replaces the previous setting. Only one active auto-forwarding rule is supported per asset per sub-account.
</Note>