Use cases

This page walks through concrete scenarios showing day-to-day use of AgentPay SDK. Each example starts with what you would say to an agent host, then shows what happens under the hood.

In all cases, transactions are signed and broadcast locally on the operator's machine. WLFI does not process, facilitate, or custody any funds.

All examples assume the SDK is installed, the wallet is set up and funded, and base policy is in place. If any of those are missing, see Install, Wallet setup, Funding, and Policy first.

Transfer USD1 to a friend

The simplest case: transfer stablecoins from your wallet to another address.

What you say to the agent:

Sign and broadcast a transfer of 5 USD1 to 0xAbC1230000000000000000000000000000004567.

Because USD1 on BSC is the default token and network, you do not need to specify either.

What the SDK does:

1. The agent checks the wallet balance with agentpay wallet --json

2. Confirms the wallet has enough USD1 and enough BNB for gas

3. Submits the transfer:

agentpay transfer \
  --network bsc \
  --token 0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d \
  --to 0xAbC1230000000000000000000000000000004567 \
  --amount 5 \
  --broadcast \
  --json

1. Policy checks the request against the per-transaction, daily, and weekly limits

2. If the amount is within policy, the daemon signs locally and broadcasts to BSC

3. The agent reports the transaction hash back

What you see:

A confirmation with the transaction hash. The 5 USD1 arrives on-chain within seconds.

A fresh default setup starts with no spending policies, so the transfer succeeds. If you have configured policy limits for USD1, ensure the transfer amount is within the allowed range.

Pay a merchant

A real-world purchase. The merchant shows a QR code or provides a wallet address.

What you say to the agent:

Sign and broadcast a transfer of 8.50 USD1 to 0x7777000000000000000000000000000000001234 for a merchant payment.

The SDK does not distinguish between a transfer to a friend and a transfer to a merchant - both are ERC-20 transfers. The flow is identical to the previous example: balance check -> policy -> sign -> broadcast. The agent confirms the transfer and shows the transaction hash.

Transfer to a contractor - with manual approval

Larger transfers can require human sign-off. This example shows what happens when a transfer exceeds the manual approval threshold.

Setup: the operator has added a manual approval rule for USD1 transfers above 50 USD1. See Manual approval for how to configure this.

What you say to the agent:

Sign and broadcast a transfer of 200 USD1 to 0xCONTRACTOR0000000000000000000000000099.

What the SDK does:

1. The agent checks balances - wallet has enough USD1 and BNB

2. Submits the transfer:

agentpay transfer \
  --network bsc \
  --token 0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d \
  --to 0xCONTRACTOR0000000000000000000000000099 \
  --amount 200 \
  --broadcast \
  --json

1. Policy check passes the spending limits, but the manual approval rule triggers because 200 > 50

2. The daemon pauses the request and returns an approval request ID

3. The CLI keeps polling for up to 5 minutes, waiting for a human decision

What you see:

The agent tells you the transfer requires approval and shows the CLI command to approve locally:

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

Once approved, the daemon signs and broadcasts automatically. The agent reports the transaction hash. No need to rerun the original command.

This is a security feature, not a failure. Routine transfers go through instantly. Larger transfers pause for human review. The threshold is configurable per token and per recipient.

Top up a short wallet

What happens when the wallet does not have enough funds.

What you say to the agent:

Sign and broadcast a transfer of 5 USD1 to 0xAbC1230000000000000000000000000000004567.

What the SDK does:

1. The agent checks the wallet balance

2. Discovers the wallet has only 2 USD1, or has no BNB for gas

3. Instead of attempting and failing, the agent stops and shows funding instructions

What you see:

The agent reports the shortfall and shows:

• the wallet address to fund

• the network (BSC, chain ID 56)

• which asset is short (USD1, BNB, or both)

• a QR code for mobile top-up (when the skill pack's funding helper is available)

Once the wallet address is funded, tell the agent to retry the original request.

The skill pack instructs agent hosts to check balances before submitting a transfer and to present funding instructions instead of retrying a doomed request. This is the intended behavior.

What these examples have in common

Every use case follows the same pattern:

1. You describe the intent in plain language

2. The agent checks the wallet state

3. The agent submits the request through agentpay

4. The local daemon enforces policy before signing

5. The result comes back - either a confirmed transaction, a pending approval, a funding request, or a gift card delivery confirmation

For the full workflow details, continue to Workflows.