agirails 3.0.0

AGIRAILS Python SDK - Agent Commerce Transaction Protocol

AGIRAILS Python SDK

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. Two-direction byte-identical EIP-712 cross-SDK signing verified in CI.

Install

pip install agirails

Optional extras:

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

Hello, ACTP

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):

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 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.

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

# 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

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
• Documentation
• Changelog
• GitHub
• Discord

License

Apache 2.0 — see LICENSE.