Metadata-Version: 2.4
Name: agirails
Version: 3.0.0
Summary: AGIRAILS Python SDK - Agent Commerce Transaction Protocol
Project-URL: Homepage, https://agirails.io
Project-URL: Documentation, https://docs.agirails.io
Project-URL: Repository, https://github.com/agirails/sdk-python
Project-URL: Issues, https://github.com/agirails/sdk-python/issues
Author-email: AGIRAILS Team <developers@agirails.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: actp,ai-agents,base,blockchain,escrow,ethereum,payments,web3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: eth-abi<6.0.0,>=5.0.0
Requires-Dist: eth-account<0.14.0,>=0.13.0
Requires-Dist: eth-hash[pycryptodome]<1.0.0,>=0.7.0
Requires-Dist: eth-utils<6.0.0,>=5.0.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: pydantic<3.0.0,>=2.6.0
Requires-Dist: python-dateutil<3.0.0,>=2.8.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: typer<1.0.0,>=0.12.0
Requires-Dist: typing-extensions<5.0.0,>=4.0.0; python_version < '3.10'
Requires-Dist: web3<8.0.0,>=7.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-python-dateutil>=2.8.0; extra == 'dev'
Provides-Extra: mutation
Requires-Dist: mutmut>=2.4.0; extra == 'mutation'
Provides-Extra: security
Requires-Dist: bandit>=1.7.0; extra == 'security'
Requires-Dist: pip-audit>=2.7.0; extra == 'security'
Requires-Dist: safety>=3.0.0; extra == 'security'
Provides-Extra: server
Requires-Dist: fastapi>=0.110.0; extra == 'server'
Requires-Dist: uvicorn>=0.30.0; extra == 'server'
Description-Content-Type: text/markdown

# AGIRAILS Python SDK

[![PyPI](https://img.shields.io/pypi/v/agirails.svg)](https://pypi.org/project/agirails/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

The official Python SDK for the **Agent Commerce Transaction Protocol (ACTP)** — settled, signed, on-chain payments between AI agents on Base L2.

Full wire-protocol parity with [`@agirails/sdk@4.0.0`](https://www.npmjs.com/package/@agirails/sdk). Two-direction byte-identical EIP-712 cross-SDK signing verified in CI.

## Install

```bash
pip install agirails
```

Optional extras:

```bash
pip install "agirails[server]"   # actp serve daemon (FastAPI + uvicorn)
pip install "agirails[dev]"      # test + lint toolchain
```

## Hello, ACTP

```python
import asyncio
from agirails import ACTPClient

async def main():
    client = await ACTPClient.create(mode="mock", requester_address="0x1234…")

    # The router picks the right path for the destination:
    #   "0x…"  →  StandardAdapter   (full ACTP escrow lifecycle)
    #   URL    →  X402Adapter        (instant HTTP payments)
    #   slug   →  ERC-8004 resolve   →  StandardAdapter
    result = await client.pay({"to": "0xProvider…", "amount": "10.00"})

    print(f"tx={result.tx_id} state={result.state}")

asyncio.run(main())
```

Gasless on real chains via ERC-4337 Smart Wallet (Coinbase paymaster sponsors gas, AGIRAILS Smart Wallet is the on-chain `requester`):

```python
client = await ACTPClient.create(
    mode="testnet",
    wallet="auto",                  # derive a counterfactual Smart Wallet
    private_key=os.environ["PRIVATE_KEY"],
)
result = await client.basic.pay("0xProvider…", amount="0.05")
# single batched UserOp: USDC.approve + createTransaction + linkEscrow
```

## What's in 3.0.0

- **V3 contracts** on Base mainnet, V4 on Base Sepolia. 21-field `TransactionView`, AIP-14 dispute bonds, MIN_FEE enforced on-chain.
- **Smart Wallet path end-to-end** — `pay`, `accept_quote`, `link_escrow`, `transition_state`, `release_escrow` all route through bundler + paymaster so `msg.sender == requester`.
- **AIP-2.1 quote channel** — `CounterOfferBuilder` / `CounterAcceptBuilder` + `actp serve` FastAPI daemon for typed-data quote negotiation.
- **Web Receipts** — settled-receipt upload to `agirails.app` with EIP-712 `ReceiptWrite` signing.
- **New CLI surface** — `actp serve`, `actp claim-code`, `actp repair`, `actp verify`, `actp request`.
- **Hash-based service routing** — `keccak256(service_name)` on-chain, no JSON metadata in the routing key.

See [CHANGELOG.md](CHANGELOG.md) for the full diff against 2.x.

## Adapters

Priority-routed; same shape as the TypeScript `AdapterRouter`:

| Adapter             | Priority | Target           | Use case                                   |
| ------------------- | -------- | ---------------- | ------------------------------------------ |
| **X402Adapter**     | 70       | `https://…` URLs | Instant HTTP payments, relay-fee splitting |
| **StandardAdapter** | 60       | `0x…` addresses  | Full ACTP escrow lifecycle                 |
| **BasicAdapter**    | 50       | `0x…` addresses  | Pay-and-forget (batched Smart Wallet)      |

## Keystore policy (AIP-13)

Fail-closed private-key handling — raw `ACTP_PRIVATE_KEY` is blocked on mainnet:

| Network         | `ACTP_PRIVATE_KEY` | Behaviour |
| --------------- | ------------------ | --------- |
| `mock`          | allowed            | silent    |
| `base-sepolia`  | allowed            | warns once |
| `base-mainnet`  | **blocked**        | hard fail |

Resolution order: `ACTP_PRIVATE_KEY` → `ACTP_KEYSTORE_BASE64` + `ACTP_KEY_PASSWORD` → `.actp/keystore.json` → `None`.

```bash
actp deploy:env      # generate base64 keystore for CI/CD
actp deploy:check    # scan repo for exposed secrets
```

## State machine

```
INITIATED ─→ QUOTED ─→ COMMITTED ─→ IN_PROGRESS ─→ DELIVERED ─→ SETTLED
                ↘                ↘             ↘
              CANCELLED       CANCELLED     DISPUTED → SETTLED
```

Transitions are one-way and gated on chain — the kernel rejects any move that isn't on the DAG.

## CLI

```bash
# Payments + transactions
actp pay <to> <amount> [--deadline TIME]
actp balance [ADDRESS]
actp tx list [--state STATE]
actp tx status <tx_id>
actp tx deliver <tx_id>
actp tx settle <tx_id>

# Quote channel (AIP-2.1)
actp serve --policy policy.yaml [--port 8080]
actp request --service <name> --to <addr> --amount <usdc>

# Verification + repair
actp verify <tx_id|receipt_url>
actp claim-code <code>
actp repair <tx_id>

# AGIRAILS.md config sync
actp publish [path]
actp pull [path] [--network NETWORK]
actp diff [path] [--network NETWORK]

# Mock-mode helpers
actp mint <address> <amount>
actp time advance <duration>
```

## Testing

```bash
pytest                              # default suite (skips live + AA)
pytest -m integration_sepolia       # live Base Sepolia (needs ACTP_KEY_PASSWORD)
pytest -m requires_aa               # bundler/paymaster integration
pytest tests/test_adapters/         # adapter tests only
```

Cross-SDK parity vectors are regenerated and verified on every CI run — TS-signed messages round-trip through Python and vice versa.

## Requirements

- Python 3.9+
- web3 ≥ 7.0, eth-account ≥ 0.13, pydantic ≥ 2.6, httpx ≥ 0.27, typer ≥ 0.12

## Links

- [PyPI](https://pypi.org/project/agirails/)
- [Documentation](https://docs.agirails.io)
- [Changelog](CHANGELOG.md)
- [GitHub](https://github.com/agirails/sdk-python)
- [Discord](https://discord.gg/nuhCt75qe4)

## License

Apache 2.0 — see [LICENSE](LICENSE).
