Metadata-Version: 2.4
Name: autogen-ucashpay
Version: 0.1.0
Summary: Microsoft AutoGen tools to charge per agent task via U.CASH (HTTP-402). Non-custodial.
Project-URL: Homepage, https://github.com/UdotCASH/autogen-ucashpay
Project-URL: Repository, https://github.com/UdotCASH/autogen-ucashpay
Project-URL: Documentation, https://github.com/UdotCASH/autogen-ucashpay#readme
Author: U.CASH
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,autogen,billing,http-402,payments,u.cash,ucash
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: autogen
Requires-Dist: autogen-agentchat>=0.2; extra == 'autogen'
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
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

```python
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)

```python
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.):

```python
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:

```python
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](https://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)

```bash
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](LICENSE).
