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

# Create Wallets and Deposit Addresses

> Learn how to provision an MPC wallet for any supported asset and generate deposit addresses — both isolated and omnibus — using the Finrock API.

Every asset you custody on Finrock lives inside a dedicated MPC wallet, and each wallet can hold one or more deposit addresses. This guide walks you through creating a wallet for an asset, generating the right type of deposit address for your use case, listing and labelling your addresses, and using advanced address features like Manual Sweep and Auto-Forwarding.

<Steps>
  ### Choose Your Asset

  Before creating a wallet, confirm the asset ticker you want to use. Finrock supports a broad range of assets — including `BTC`, `ETH`, `USDT_TRX`, `USDT_ETH`, `SOL`, `XRP`, and many more.

  Retrieve the full list of supported assets at any time:

  ```bash theme={null}
  curl --request GET \
       --url https://api.finrock.io/dac/v1/supported-assets \
       --header 'Authorization: Token {JWT}' \
       --header 'x-api-key: YOUR_API_KEY' \
       --header 'accept: application/json'
  ```

  Note the exact `asset` string from the response — you will use it in every subsequent request.

  ### Create a Wallet

  Create one MPC wallet per asset per sub-account. If you try to create a duplicate wallet for the same asset in the same sub-account, the API returns the existing wallet rather than creating a new one.

  <CodeGroup>
    ```bash cURL theme={null}
    curl --request POST \
         --url https://api.finrock.io/dac/v1/create-wallet \
         --header 'Authorization: Token {JWT}' \
         --header 'x-api-key: YOUR_API_KEY' \
         --header 'content-type: application/json' \
         --header 'accept: application/json' \
         --data '{"asset": "ETH"}'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch('https://api.finrock.io/dac/v1/create-wallet', {
      method: 'POST',
      headers: {
        'Authorization': 'Token YOUR_JWT',
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      body: JSON.stringify({ asset: 'ETH' }),
    });

    const wallet = await response.json();
    console.log(wallet);
    ```
  </CodeGroup>

  A successful `200` response returns the new wallet object. Save the wallet identifier for future address generation requests.

  ### Generate a Deposit Address

  Once your wallet exists, generate one or more deposit addresses for it. The two key flags — `omnibus` and `auto_refill` — control how funds are pooled and how gas fees are funded.

  <CodeGroup>
    ```bash cURL theme={null}
    curl --request POST \
         --url https://api.finrock.io/dac/v1/generate-address \
         --header 'Authorization: Token {JWT}' \
         --header 'x-api-key: YOUR_API_KEY' \
         --header 'content-type: application/json' \
         --header 'accept: application/json' \
         --data '{
           "asset": "ETH",
           "label": "customer-deposits",
           "omnibus": false,
           "auto_refill": false
         }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch('https://api.finrock.io/dac/v1/generate-address', {
      method: 'POST',
      headers: {
        'Authorization': 'Token YOUR_JWT',
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      body: JSON.stringify({
        asset: 'ETH',
        label: 'customer-deposits',
        omnibus: false,
        auto_refill: false,
      }),
    });

    const address = await response.json();
    console.log(address);
    ```
  </CodeGroup>

  **Request body parameters:**

  | Field         | Type    | Required             | Description                                                                   |
  | ------------- | ------- | -------------------- | ----------------------------------------------------------------------------- |
  | `asset`       | string  | Yes                  | Asset ticker from the supported-assets list                                   |
  | `label`       | string  | Yes                  | A human-readable name describing this address's purpose                       |
  | `omnibus`     | boolean | No (default `false`) | `false` = isolated address; `true` = address joins the shared omnibus pool    |
  | `auto_refill` | boolean | No (default `false`) | When `true`, gas fees are automatically funded from your Gas Tank when needed |

  <Note>
    **Omnibus vs. Isolated Addresses**

    * An **isolated address** (`omnibus: false`) holds funds in a dedicated on-chain address assigned to one specific purpose or customer. Balances remain segregated and you control sweeping manually.
    * An **omnibus address** (`omnibus: true`) pools incoming deposits into a single shared wallet, reducing gas overhead at scale. All omnibus addresses should set `auto_refill: true` so gas refills happen automatically.

    For high-volume deposit flows with many end-users, omnibus addresses are the recommended pattern. See the [Omnibus Wallets](/concepts/omnibus-wallets) concept page for architecture details.
  </Note>

  ### List Your Addresses

  Retrieve all deposit addresses for a given asset to verify creation or audit your address inventory:

  ```bash theme={null}
  curl --request GET \
       --url 'https://api.finrock.io/dac/v1/addresses?asset=ETH' \
       --header 'Authorization: Token {JWT}' \
       --header 'x-api-key: YOUR_API_KEY' \
       --header 'accept: application/json'
  ```

  The response returns a paginated list of address objects, each containing the address string, label, omnibus flag, auto\_refill flag, and current balance.

  ### Edit an Address Label

  Update the label or change the `omnibus` and `auto_refill` settings on an existing address without recreating it:

  ```bash theme={null}
  curl --request POST \
       --url https://api.finrock.io/dac/v1/edit-address \
       --header 'Authorization: Token {JWT}' \
       --header 'x-api-key: YOUR_API_KEY' \
       --header 'content-type: application/json' \
       --header 'accept: application/json' \
       --data '{
         "asset": "ETH",
         "address": "0xYourAddressHere",
         "address_tag": "",
         "label": "premium-customer-deposits",
         "auto_refill": true
       }'
  ```

  **Request body parameters:**

  | Field         | Type    | Required | Description                                                                 |
  | ------------- | ------- | -------- | --------------------------------------------------------------------------- |
  | `asset`       | string  | Yes      | Asset ticker from the supported-assets list                                 |
  | `address`     | string  | Yes      | The on-chain address to edit                                                |
  | `address_tag` | string  | Yes      | Destination tag or memo (leave empty string for chains that don't use tags) |
  | `label`       | string  | No       | Updated human-readable label for this address                               |
  | `omnibus`     | boolean | No       | Updated only when explicitly set to `true` or `false`                       |
  | `auto_refill` | boolean | No       | Updated only when explicitly set to `true` or `false`                       |

  Use this endpoint whenever you need to re-classify an address or enable auto gas refill after initial creation.
</Steps>

## Manual Sweep

Manual Sweep lets you consolidate all funds from a non-omnibus (isolated) address directly into the omnibus wallet in a single operation. This is useful for periodic consolidation or when you need to move balances before closing an isolated address.

Call `POST /dac/v1/invoke-sweep` with the asset and the source address:

```bash theme={null}
curl --request POST \
     --url https://api.finrock.io/dac/v1/invoke-sweep \
     --header 'Authorization: Token {JWT}' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --header 'accept: application/json' \
     --data '{
       "asset": "ETH",
       "address": "0xYourIsolatedAddressHere"
     }'
```

<Warning>
  Manual Sweep works only for **non-omnibus** addresses. The sweep moves the **entire balance** of the specified asset. The operation will fail if your [Gas Tank](/concepts/gas-tanks) does not hold sufficient funds to cover the network fee — top up your Gas Tank before invoking a sweep if needed.
</Warning>

## Auto-Forwarding

Auto-Forwarding automatically routes incoming deposits from a Finrock address to a designated external address on a configurable schedule. This is ideal for treasury flows where you want funds to leave the platform on a regular cadence without manual intervention.

Configure Auto-Forwarding with `POST /dac/v1/auto-forwarding`:

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

**Frequency options:**

| Value      | Behaviour                                                       |
| ---------- | --------------------------------------------------------------- |
| `Nightly`  | Batches all incoming funds and forwards them once per night     |
| `RealTime` | Forwards funds to the external address immediately upon receipt |

<Tip>
  Use `Nightly` frequency to consolidate multiple small deposits into a single forwarding transaction, reducing total network fees. Use `RealTime` when your downstream system requires immediate settlement.
</Tip>