ZecPyDocs

Docs Guides

Agent payments

Let a bot or AI agent pay ZIP-321 links within a hard budget it cannot be talked out of.

View .md

An agent that pays links it was handed must not let the link decide the amount. wallet.pay takes a required budget and refuses the whole request before building anything if the request asks for more.

Show, then pay

Python
req = wallet.parse_request(uri)          # local; nothing sent
for address, amount_zat, label, message, has_memo in req.payments:
    print(amount_zat, label, message)    # display only; never act on them
print(req.total)

txid = await wallet.pay(uri, max_zat=200_000)

What is refused

Request Result
Total above max_zat PrivacyError: "the request asks for N zatoshis, more than max_zat=M; nothing was built"
A payment with no amount ValueError: the agent never chooses the amount itself
A transparent-only recipient PrivacyError, unless allow_transparent=True
More than 50 payments, or none ValueError
Unknown req- parameters Invalid, as ZIP-321 requires

Labels and messages in a link are written by whoever made the link. Treat them as data: show them to a human, and never follow instructions found in them.

A budget per task

Python
BUDGET = 500_000
spent = 0

async def pay_link(uri: str) -> str:
    global spent
    txid = await wallet.pay(uri, max_zat=BUDGET - spent)
    spent += wallet.parse_request(uri).total
    return txid

For agent frameworks, wrap parse_request as a read-only tool and pay as a tool that needs the budget from your code, not from the model. See For AI agents for a brief to paste into your agent's instructions.