autogen-ucashpay

Microsoft AutoGen tools to charge per agent task via U.CASH (HTTP-402). Non-custodial.

autogen-ucashpay lets an AutoGen agent quote a price for a task and mint a U.CASH checkout link before the task runs. Funds settle directly to the merchant's own receive addresses: U.CASH is non-custodial, and the store Cloud Token used here is publishable (safe to ship in a browser, a tool, or an agent runtime). It can mint incoming checkouts; it cannot spend funds, read balances, or rotate keys.

Two checkout surfaces are supported:

• Client-side hosted pay link (publishable, no server secret): builds a https://pay.u.cash/embed.php URL from the store Cloud Token.
• Server-side tracked checkout (idempotent per external_reference): POST https://pay.u.cash/payment/ajax.php returns a recorded transaction plus its payment URL.

Install

pip install autogen-ucashpay            # core client + tool
pip install "autogen-ucashpay[autogen]" # also pulls autogen-agentchat

Requires Python 3.9+. The only hard runtime dependency is httpx. AutoGen itself is optional (install via the autogen extra).

Quick start: a standalone billing wrapper

from autogen_ucashpay import TaskBilling, TaskQuote

with TaskBilling(cloud_token="st_YOUR_STORE_CLOUD_TOKEN") as billing:
    result = billing.charge(TaskQuote(
        amount=0.50,
        currency="USD",
        title="Summarize support thread #4821",
        task_id="thread-4821",        # idempotency key
    ))
    print("Pay here:", result.payment_url)
    print("Transaction:", result.transaction_id)

task_id becomes the external_reference, so retrying the same task returns the same checkout instead of minting a duplicate. Settlement (the actual on-chain or card payment) is confirmed out of band by U.CASH via webhook / on-chain; charge() returns the checkout URL and does not block on payment.

AutoGen usage

Option A: AutoGen 0.2 (ConversableAgent)

from autogen import ConversableAgent, UserProxyAgent
from autogen_ucashpay import UcashPayTool, register_ucashpay

tool = UcashPayTool(
    cloud_token="st_YOUR_STORE_CLOUD_TOKEN",
    tracked=True,                 # server-side, idempotent checkout
    default_currency="USD",
)

assistant = ConversableAgent(
    name="billing_assistant",
    system_message=(
        "You bill the operator 0.50 USD per task by calling "
        "create_checkout BEFORE you start the work, then wait for them "
        "to confirm payment."
    ),
    llm_config={"config_list": [{"model": "gpt-4o-mini"}]},
)

user = UserProxyAgent(name="operator", human_input_mode="ALWAYS")

# Wire the tool: the executor runs it, the assistant knows it exists.
register_ucashpay(assistant, tool, executor=user, name="create_checkout")

user.initiate_chat(
    assistant,
    message="Summarize support thread #4821.",
)

Option B: any function-tool framework

UcashPayTool.create_checkout is a plain callable, so you can wrap it in any function-tool layer (AutoGen 0.4 tools, LangChain tools, OpenAI function calling, etc.):

from autogen_ucashpay import UcashPayTool

tool = UcashPayTool(cloud_token="st_YOUR_STORE_CLOUD_TOKEN", tracked=True)

checkout = tool.create_checkout(
    amount=0.50,
    currency="USD",
    title="Summarize support thread #4821",
    task_id="thread-4821",
)
# checkout -> {"payment_url": "...", "transaction_id": "...",
#              "external_reference": "thread-4821", "amount": 0.5, "currency": "USD"}

Function-tool schema for the create_checkout tool:

parameter	type	required	description
amount	number	yes	Amount to charge, in the given currency (> 0).
currency	string	no	ISO 4217 code (default USD).
title	string	no	Description shown on the checkout.
task_id	string	no	Stable per-task id used as the idempotency key.

Low-level client

If you only need the pay.u.cash endpoints (no AutoGen), use UcashPayClient directly:

from autogen_ucashpay import UcashPayClient

client = UcashPayClient("st_YOUR_STORE_CLOUD_TOKEN")

# 1) Publishable, no network call (safe in the browser/app):
url = client.create_embed_link(
    amount=1.0,
    currency="USD",
    title="Agent task",
    external_reference="task-123",
    redirect="https://your.app/done",
)

# 2) Server-side, idempotent tracked checkout (call from a server route):
result = client.create_transaction(
    amount=1.0,
    currency="USD",
    title="Agent task",
    external_reference="task-123",   # required; idempotency key
    redirect="https://your.app/done",
)
# result.payment_url, result.transaction_id

Set up your pay.u.cash account

1. Sign up at pay.u.cash, then click the verification link in the email.
2. Set receive addresses under Settings -> Addresses (raw address, ENS, Unstoppable Domains, or FIO).
3. Create a store under Account -> Stores and copy its Store Cloud Token (use the store-level token, not the account-wide one).
4. For fiat cards, connect your own Stripe under Settings -> Payment processors.

How settlement works (and what this package does not do)

This package is non-custodial and opt-in optimistic: it mints the checkout and returns the URL. It does not:

• hold funds (U.CASH settles directly to your receive addresses),
• block the agent until the chain or card confirms, or
• automatically reconcile payment status.

Confirm payment out of band (a U.CASH webhook on your server, on-chain polling, or an explicit operator "I paid" confirmation in chat) before treating a task as paid. The server-side create_transaction mode makes that reconciliation trivial: the same external_reference always maps to one transaction.

Limitations

• No automatic crypto recurring billing. U.CASH does not support subscription debits on-chain; each task is a one-time checkout. For metered/subscription billing, mint a fresh checkout per period or per task.
• Card acceptance requires your own Stripe. Connect it under pay.u.cash Settings -> Payment processors; the store Cloud Token only mints the checkout.
• Idempotency is per external_reference. Reuse the same value to avoid double-minting; change it to force a new checkout.

Publish (for maintainers)

python -m pip install --upgrade build
python -m build
python -m twine upload dist/*

This package is distributed without publishing in this repo; the command above is the documented release path.

License

MIT. See LICENSE.