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

# Sub Accounts

> Manage sub-accounts and delegation tokens from the ZendFi CLI.

# CLI Sub Accounts

Use the `subaccounts` command group (alias: `sa`) to operate merchant sub-accounts.

## Commands

| Command                                                    | Description                                              |
| ---------------------------------------------------------- | -------------------------------------------------------- |
| `zendfi subaccounts create --label <label>`                | Create a sub-account                                     |
| `zendfi subaccounts list`                                  | List all sub-accounts                                    |
| `zendfi subaccounts get <id>`                              | Get a sub-account by UUID or external ID                 |
| `zendfi subaccounts balance <id>`                          | Get current SOL/USDC balances                            |
| `zendfi subaccounts ttl-policy-get`                        | Get merchant sub-account TTL policy                      |
| `zendfi subaccounts ttl-policy-set`                        | Update merchant sub-account TTL policy overrides         |
| `zendfi subaccounts token <id>`                            | Mint a scoped delegation token                           |
| `zendfi subaccounts token-child <id>`                      | Mint an attenuated child delegation token                |
| `zendfi subaccounts freeze <id>`                           | Freeze sub-account and revoke active delegation tokens   |
| `zendfi subaccounts unfreeze <id>`                         | Unfreeze a frozen sub-account (tokens remain revoked)    |
| `zendfi subaccounts drain <id>`                            | Drain funds back to merchant wallet                      |
| `zendfi subaccounts withdraw <id>`                         | Withdraw to external wallet                              |
| `zendfi subaccounts withdraw-bank <id>`                    | Withdraw to bank with automated proxy-email OTP flow     |
| `zendfi subaccounts automation-token-mint`                 | Mint bounded automation token for headless withdraw-bank |
| `zendfi subaccounts automation-token-revoke <token-id>`    | Revoke automation token                                  |
| `zendfi subaccounts signing-grant-mint`                    | Mint bounded signing grant for headless signing          |
| `zendfi subaccounts signing-grant-revoke <grant-id>`       | Revoke signing grant                                     |
| `zendfi subaccounts policy-create`                         | Create versioned policy                                  |
| `zendfi subaccounts policy-dry-run`                        | Evaluate policy without persisting                       |
| `zendfi subaccounts trigger-create`                        | Create reactive webhook trigger subscription             |
| `zendfi subaccounts trigger-list`                          | List trigger subscriptions                               |
| `zendfi subaccounts intent-create`                         | Create execution intent                                  |
| `zendfi subaccounts intent-approve <intent-id>`            | Approve or reject execution intent                       |
| `zendfi subaccounts intent-release --signal-token <token>` | Release intent using signal token                        |
| `zendfi subaccounts balance-rule-create`                   | Create balance automation rule                           |
| `zendfi subaccounts close <id>`                            | Close sub-account                                        |

## Create

```bash theme={null}
zendfi subaccounts create \
  --label user_paschal_001 \
  --spend-limit 500 \
  --access-mode delegated
```

## List

```bash theme={null}
zendfi subaccounts list
```

## Balance

```bash theme={null}
zendfi subaccounts balance sa_xxxxx
```

## TTL Policy (Merchant)

```bash theme={null}
zendfi subaccounts ttl-policy-get
```

```bash theme={null}
zendfi subaccounts ttl-policy-set \
  --signing-grant-max-ttl 1209600 \
  --automation-token-max-ttl 1209600 \
  --child-delegation-max-ttl 259200
```

Token and grant TTL inputs are validated against these effective policy values.

## Mint Delegation Token

```bash theme={null}
zendfi subaccounts token sa_xxxxx \
  --scope withdraw_only \
  --spend-limit 100 \
  --ttl 900 \
  --whitelist 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU \
  --single-use \
  --policy-version-id a6e9db6f-e264-4f9d-a4c7-7f94b18f0f34 \
  --agent-label risk-bot-v2
```

## Mint Child Delegation Token

```bash theme={null}
zendfi subaccounts token-child sa_xxxxx \
  --parent-delegation-token satk_parent_xxxxx \
  --scope withdraw_only \
  --spend-limit 25 \
  --ttl 900 \
  --single-use
```

## Freeze

```bash theme={null}
zendfi subaccounts freeze sa_xxxxx --reason "fraud-review"
```

## Unfreeze

```bash theme={null}
zendfi subaccounts unfreeze sa_xxxxx --reason "manual-review-cleared"
```

Previously revoked delegation tokens are not reactivated; mint new token(s) after unfreeze if required.

## Drain

```bash theme={null}
zendfi subaccounts drain sa_xxxxx \
  --amount 25 \
  --token Usdc \
  --mode live \
  --passkey-file ./passkey-signature.json
```

## Withdraw

```bash theme={null}
zendfi subaccounts withdraw sa_xxxxx \
  --to 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU \
  --amount 10 \
  --token Usdc \
  --mode live \
  --delegation-token satk_xxxxx \
  --signing-grant ssgt_xxxxx \
  --execution-intent-id 89d52313-1cea-4313-80a4-23afc543287e
```

`--signing-grant` and `--passkey-file` are mutually exclusive.

`--passkey-file` remains available as an interactive fallback.

## Withdraw to Bank (One-Shot)

```bash theme={null}
zendfi subaccounts withdraw-bank sa_xxxxx \
  --amount 25 \
  --bank-id GTB \
  --account-number 0123456789 \
  --mode live \
  --signing-grant ssgt_xxxxx \
  --automation-token saatk_xxxxx \
  --delegation-token satk_xxxxx \
  --execution-intent-id 89d52313-1cea-4313-80a4-23afc543287e
```

This command mirrors split proxy-email OTP automation. No manual OTP prompt is required.

`--automation-token` and `--delegation-token` are mutually exclusive.

`--signing-grant` and `--passkey-file` are mutually exclusive.

For API-key initiated withdraw-bank calls, pass one policy token (`--automation-token` or `--delegation-token`) and one signing authorization (`--signing-grant`).

`--bank-id` accepts a bank identifier value (PAJ bank id, bank code, or bank name).

## Mint Automation Token

```bash theme={null}
zendfi subaccounts automation-token-mint \
  --subaccount-id sa_xxxxx \
  --ttl 3600 \
  --max-uses 25 \
  --total-limit 500 \
  --per-tx-limit 50 \
  --bank-ids GTB \
  --account-numbers 0123456789 \
  --mode live \
  --policy-version-id a6e9db6f-e264-4f9d-a4c7-7f94b18f0f34 \
  --parent-token-id c4fab649-f4f0-438f-8dc8-9737a82c59d3 \
  --agent-label reconciliation-agent
```

## Revoke Automation Token

```bash theme={null}
zendfi subaccounts automation-token-revoke 0f8fad5b-d9cb-469f-a165-70867728950e
```

## Mint Signing Grant

```bash theme={null}
zendfi subaccounts signing-grant-mint \
  --subaccount-id sa_xxxxx \
  --ttl 3600 \
  --max-uses 25 \
  --total-limit 500 \
  --per-tx-limit 50 \
  --bank-ids GTB \
  --account-numbers 0123456789 \
  --mode live \
  --policy-version-id a6e9db6f-e264-4f9d-a4c7-7f94b18f0f34 \
  --parent-grant-id e9ae9bc0-e640-4a2b-a7e8-d85b93b1a8a0 \
  --active-days-utc 1,2,3,4,5 \
  --active-start-utc 09:00 \
  --active-end-utc 18:00 \
  --auto-renew
```

This command starts a browser intent, opens the approval URL, and polls until passkey approval completes.

Legacy fallback (manual payload) remains available:

```bash theme={null}
zendfi subaccounts signing-grant-mint \
  --subaccount-id sa_xxxxx \
  --ttl 3600 \
  --max-uses 25 \
  --total-limit 500 \
  --per-tx-limit 50 \
  --mode live \
  --passkey-file ./passkey-signature.json
```

Use `--no-open` if your environment cannot auto-open a browser.

`--ttl` must be within merchant TTL policy bounds.

## Revoke Signing Grant

```bash theme={null}
zendfi subaccounts signing-grant-revoke 2f8fad5b-d9cb-469f-a165-70867728950e
```

## Create Policy

```bash theme={null}
zendfi subaccounts policy-create \
  --subaccount-id sa_xxxxx \
  --policy-type signing_grant \
  --status active \
  --policy-json '{"max_per_tx_usdc":100,"max_per_day_usdc":500,"allowed_modes":["live"]}'
```

## Dry Run Policy

```bash theme={null}
zendfi subaccounts policy-dry-run \
  --subaccount-id sa_xxxxx \
  --amount 25 \
  --mode live \
  --daily-spend 120 \
  --policy-json '{"max_per_tx_usdc":100,"max_per_day_usdc":500,"allowed_modes":["live"]}'
```

## Create Trigger Subscription

```bash theme={null}
zendfi subaccounts trigger-create \
  --subaccount-id sa_xxxxx \
  --trigger-type balance_below \
  --threshold 20 \
  --cooldown 300
```

## List Trigger Subscriptions

```bash theme={null}
zendfi subaccounts trigger-list
```

## Create Execution Intent

```bash theme={null}
zendfi subaccounts intent-create \
  --subaccount-id sa_xxxxx \
  --intent-type withdraw_to_bank \
  --signal-type webhook_ack \
  --expires 900 \
  --payload '{"bank_id":"GTB","account_number":"0123456789"}'
```

## Approve Execution Intent

```bash theme={null}
zendfi subaccounts intent-approve 89d52313-1cea-4313-80a4-23afc543287e
```

Reject example:

```bash theme={null}
zendfi subaccounts intent-approve 89d52313-1cea-4313-80a4-23afc543287e --reject --reason "limit exceeded"
```

## Release Execution Intent By Signal

```bash theme={null}
zendfi subaccounts intent-release --signal-token sge_xxxxx
```

## Create Balance Rule

```bash theme={null}
zendfi subaccounts balance-rule-create \
  --subaccount-id sa_xxxxx \
  --rule-name keep-hot-wallet-funded \
  --rule-type topup_below \
  --threshold 50 \
  --action-amount 100 \
  --max-actions-per-day 6 \
  --cooldown 300
```

## Close

```bash theme={null}
zendfi subaccounts close sa_xxxxx
```

## Passkey Signature File

Interactive fallback operations can use `--passkey-file` JSON with this shape:

```json theme={null}
{
  "credential_id": "...",
  "authenticator_data": [1, 2, 3],
  "signature": [4, 5, 6],
  "client_data_json": [7, 8, 9]
}
```