Manual approval

Manual approval is an optional layer you add after the base policy is working. Use it when some requests should pause for human sign-off even though smaller routine requests go through automatically. All signing and broadcasting remains local - WLFI is not involved in any transfer of funds.

When to add manual approval

Add manual approval only after the base policy is defined.

Typical use cases:

• routine transfers should go through automatically, but larger transfers should pause

• a specific token should require approval above a threshold

• a request to a sensitive recipient should require an explicit human decision

Where you define it

The clearest place to define manual approval is the Tokens view in agentpay admin tui. Manual approval is attached to the selected token and network context, which is why it belongs after the base token policy is already in place.

Minimal TUI path

Use this when you want to add a simple approval range:

1. Open agentpay admin tui.

2. Go to Tokens.

3. Select the token whose requests should be approval-gated.

4. Confirm the correct network mapping in Editing Network.

5. Add a manual approval draft with Ctrl+M or the Add Manual Approval field.

6. Fill in the approval rule:

   • Approval Recipient if the rule should apply to one recipient only

   • Approval Min Amount

   • Approval Max Amount

   • Approval Priority

7. Save the token.

8. Go to Bootstrap and apply the saved inventory.

If you leave Approval Recipient blank, the rule can apply across recipients for that token and network scope.

If Approval Min Amount is omitted, the rule defaults to 0 wei, effectively triggering approval for any transfer amount within the max range. Amounts that exceed Approval Max Amount are hard-denied by the policy engine - they do not enter the approval flow.

Direct CLI path

If you prefer the command line over the TUI, use admin add-manual-approval-policy directly:

# 50 USD1 min (18 decimals = 50 × 10^18 wei), 1000 USD1 max, BSC (chain 56)
agentpay admin add-manual-approval-policy \
  --min-amount-wei 50000000000000000000 \
  --max-amount-wei 1000000000000000000000 \
  --network 56 \
  --json

Supported flags:

Flag	Required	Default	Description
--min-amount-wei <wei>	Yes	-	Minimum transfer amount (in wei) that triggers approval
--max-amount-wei <wei>	Yes	-	Maximum transfer amount (in wei) covered by this rule
--priority <n>	No	100	Evaluation priority (lower = evaluated first)
--token <address>	No	all assets	ERC-20 token scope (repeatable)
--allow-native-eth	No	false	Include the native asset in scope
--network <chain-id>	No	all networks	Restrict the rule to a single chain ID
--recipient <address>	No	all recipients	Restrict the rule to a single recipient

After creating the rule, apply the updated policy set with agentpay admin tui (Bootstrap view) or rerun setup with --attach-bootstrap-policies.

Manual approval is an overlay, not an override. Matching transfers must still satisfy every stricter hard limit (per-tx, daily, weekly, gas, fee, calldata caps) before they reach the approval flow. A manual approval rule does not relax hard spending limits.

To inspect current policies:

agentpay admin list-policies --json
agentpay admin list-policies --policy-id <UUID> --json

Where manual approval happens

Manual approval happens at request time, not when policy is saved.

The runtime flow looks like this:

1. A transfer or approval request is submitted

2. Policy checks the request

3. If the request matches a manual approval rule, it pauses instead of proceeding automatically

4. The CLI or host returns an approval request id

5. The operator approves or rejects the request

A host should present manual approval as a pending request, not as a failed transfer.

Approve from the CLI

Approve or reject pending requests from the terminal:

agentpay admin list-manual-approval-requests
agentpay admin approve-manual-approval-request --approval-request-id <UUID>
agentpay admin reject-manual-approval-request --approval-request-id <UUID> --rejection-reason "user rejected"
agentpay admin resume-manual-approval-request --approval-request-id <UUID>

Use resume-manual-approval-request when the original broadcast command has already exited after approval was granted.

resume-manual-approval-request also supports --rpc-url (override the RPC endpoint for the resumed broadcast), --no-wait (skip waiting for an on-chain receipt), --vault-password-stdin, --non-interactive, --daemon-socket, and --json.

The CLI is the approval path for all manual approval requests.

Broadcast auto-wait

When a request hits manual approval during transfer --broadcast, transfer-native --broadcast, or approve --broadcast, the CLI keeps the original process alive and polls the daemon every 2 seconds for up to 5 minutes. If the request is approved within that window, the CLI continues automatically - do not rerun the original command.

If the original broadcast command has already exited after approval:

agentpay admin resume-manual-approval-request --approval-request-id <UUID>

Commands outside the --broadcast flow still print the approval details and exit immediately, so you approve or reject separately.

Approval output shape

When a request triggers manual approval, the CLI returns a JSON object with:

{
  "command": "transfer",
  "approval_request_id": "<UUID>",
  "cli_approval_command": "agentpay admin approve-manual-approval-request --approval-request-id <UUID>"
}

The CLI exits with a non-zero exit code to signal that the request is pending, not failed.

Continue to Transfers for the full transfer command reference.