Metadata-Version: 2.4
Name: veto-pay
Version: 0.6.2
Summary: One-line agent payments with Veto enforcement. Any rail.
Project-URL: Homepage, https://veto-ai.com
Project-URL: Documentation, https://github.com/veto-protocol/docs
Project-URL: Source, https://github.com/veto-protocol/veto-pay
Author-email: Investech Global LLC <tomer@veto-ai.com>
License: MIT
Keywords: agents,ai,evm,payments,solana,stablecoins,veto,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: base58>=2.1; extra == 'all'
Requires-Dist: borsh-construct>=0.1; extra == 'all'
Requires-Dist: eth-abi>=5; extra == 'all'
Requires-Dist: eth-account>=0.13; extra == 'all'
Requires-Dist: eth-utils>=4; extra == 'all'
Requires-Dist: solana>=0.32; extra == 'all'
Requires-Dist: solders>=0.20; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: evm
Requires-Dist: eth-abi>=5; extra == 'evm'
Requires-Dist: eth-account>=0.13; extra == 'evm'
Requires-Dist: eth-utils>=4; extra == 'evm'
Provides-Extra: solana
Requires-Dist: base58>=2.1; extra == 'solana'
Requires-Dist: borsh-construct>=0.1; extra == 'solana'
Requires-Dist: solana>=0.32; extra == 'solana'
Requires-Dist: solders>=0.20; extra == 'solana'
Description-Content-Type: text/markdown

<div align="center">

<br>

<img src="https://veto-ai.com/veto-logo.png" alt="Veto" width="180">

<br><br>

<h3>One-line agent payments. Any rail.</h3>

<p>
  <code>pay()</code> — authorize, sign, settle.<br>
  Veto runs the policy + risk engine; the rail does the rest.
</p>

<p>
  <a href="https://pypi.org/project/veto-pay/"><img src="https://img.shields.io/pypi/v/veto-pay.svg?style=flat-square&color=06B6D4&label=pypi" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license"></a>
</p>

</div>

---

## Install

```bash
# Decision-only (no on-chain settlement) — lightest install
pip install veto-pay

# With EVM settlement (Base / Optimism / Arbitrum / Ethereum / Polygon)
pip install veto-pay[evm]

# With Solana settlement
pip install veto-pay[solana]

# Both
pip install veto-pay[all]
```

---

## Quick start

```python
from veto_pay import pay, VetoDenied

result = await pay(
    url="https://api.weather.x402.io/forecast",
    max_amount="$0.05",
    rail="auto",            # auto | evm | solana
)
print(result.tx_hash)       # on-chain tx hash on success
print(result.receipt)       # signed Veto receipt — verify offline if you want
```

If Veto denies, you get a typed exception:

```python
try:
    await pay(url=url, max_amount="$10000")
except VetoDenied as e:
    print(e.reason_codes)   # ['AMOUNT_CAP_EXCEEDED']
    print(e.receipt)        # signed receipt explaining the deny
```

---

## What it does

1. **Authorize** — `POST /api/v1/authorize` with the spend intent. Veto's 8-stage engine runs (policy / prompt-injection / typosquat / OFAC / address-poisoning / intent / anomaly / baseline / decision).
2. **Branch on decision**:
   - `deny` → raises `VetoDenied(reason_codes=...)`. No tx is made.
   - `escalate` → raises `VetoDenied` (escalations require human review before they can settle).
   - `allow` → continue.
3. **Settle on the rail**:
   - **EVM**: calls `VetoGuardedAccount.executeWithMandate(struct, sig, amount)` on the agent's smart wallet.
   - **Solana**: builds a 2-instruction tx (Ed25519 verify + `veto_guarded_program::execute_with_mandate`) and submits to the Solana RPC.
4. **Returns** the receipt + on-chain tx hash.

---

## Configuration

Environment variables (or pass as kwargs):

| Variable | Required for | Description |
|----------|-------------|-------------|
| `VETO_API_KEY` | always | Bearer token from the Veto dashboard |
| `VETO_AGENT_ID` | always | UUID of the agent (created by `veto agent init`) |
| `VETO_BASE_URL` | optional | Override the Veto API base. Default `https://veto-ai.com`. |
| `WALLET_PRIVATE_KEY` | EVM + Solana settle | Agent's private key. EVM: 0x-hex. Solana: base58. |
| `WALLET_CONTRACT` | EVM settle | The deployed `VetoGuardedAccount` address. Set by `veto agent init`. |
| `RPC_URL` | EVM settle | EVM RPC endpoint. Auto-detected from `chain=` if unset. |
| `SOLANA_RPC_URL` | Solana settle | Solana RPC. Defaults to Devnet. |
| `VETO_GUARDED_PROGRAM_ID` | Solana settle | Program ID of the deployed Solana program. |
| `VETO_RAIL` | optional | `evm` or `solana` — overrides the auto detection. |

---

## Decision-only mode

For cooperative-mode integrations (no on-chain settlement, just verdict + receipt):

```python
result = await pay(
    url=url, max_amount="$0.05", decision_only=True
)
# result.tx_hash is None; result.decision + result.receipt are populated.
```

Useful when:
- The rail handles settlement upstream (e.g., pay.sh's hosted x402 facilitator)
- You're running a dry-run before flipping enforcement on
- You're auditing decisions without enforcing them

---

## Tests

```bash
pip install -e .[dev,evm,solana]
pytest
```

---

## Public artifacts

| Artifact | Repository |
|----------|------------|
| This package | [veto-protocol/veto-pay](https://github.com/veto-protocol/veto-pay) |
| Companion JS  | [veto-protocol/veto-pay-js](https://github.com/veto-protocol/veto-pay-js) |
| Veto CLI      | [veto-protocol/veto-cli](https://github.com/veto-protocol/veto-cli) |
| EVM contract  | [veto-protocol/contracts](https://github.com/veto-protocol/contracts) |
| Solana program| [veto-protocol/solana-program](https://github.com/veto-protocol/solana-program) |
| Off-chain verifier (TS) | [veto-protocol/mandate-verifier](https://github.com/veto-protocol/mandate-verifier) |

---

## License

MIT.

---

<div align="center">

**One line. Any rail. Safe transactions.**<br>
<sub>Built by <a href="https://veto-ai.com">Investech Global LLC</a> · part of the <a href="https://github.com/veto-protocol">veto-protocol</a> family.</sub>

</div>
