agirails 2.3.2

AGIRAILS Python SDK - Agent Commerce Transaction Protocol

AGIRAILS Python SDK

The official Python SDK for the Agent Commerce Transaction Protocol (ACTP) — enabling AI agents to transact with each other through blockchain-based escrow on Base L2.

Full 1:1 parity with TypeScript SDK v2.5.0+.

Install

pip install agirails==2.3.1

Features

• Adapter Routing — priority-based adapter selection (Standard, Basic, X402)
• x402 Payments — HTTP-based instant payments with relay fee splitting
• ERC-8004 Identity — on-chain agent identity resolution and reputation
• Keystore Security (AIP-13) — fail-closed private key policy, ACTP_KEYSTORE_BASE64 for CI/CD
• AGIRAILS.md Source of Truth — parse, hash, publish, pull, diff agent configs
• Smart Wallet (ERC-4337) — batched transactions with paymaster gas sponsorship
• Lazy Publish — mainnet activation deferred to first real transaction
• Three-tier API — Basic, Standard, and Advanced levels
• Mock Runtime — full local testing without blockchain
• CLI — actp pay, publish, pull, diff, deploy:env, deploy:check
• Async-first — built on asyncio
• 1,738 tests passing

Quick Start

import asyncio
from agirails import ACTPClient

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

    # Adapter router auto-selects the best path
    # EVM address → ACTP (StandardAdapter)
    result = await client.pay({"to": "0xProvider...", "amount": "10.00"})

    # HTTP URL → x402 instant payment
    result = await client.pay({"to": "https://api.example.com/pay", "amount": "5.00"})

    # Agent ID → ERC-8004 resolve → ACTP
    result = await client.pay({"to": "12345", "amount": "10.00"})

    print(f"Transaction: {result.tx_id}, State: {result.state}")

asyncio.run(main())

Adapter Routing

Priority-based adapter selection matching TypeScript AdapterRouter:

Adapter	Priority	Target	Use Case
X402Adapter	70	https://... URLs	Instant HTTP payments with relay fee splitting
StandardAdapter	60	0x... addresses	Full ACTP lifecycle with escrow
BasicAdapter	50	0x... addresses	Simple pay-and-forget (Smart Wallet batched)

Keystore & Deployment Security (AIP-13)

Fail-closed private key policy with network-aware enforcement:

Network	ACTP_PRIVATE_KEY	Behavior
mock	Allowed	Silent
testnet (base-sepolia)	Allowed	Warn once
mainnet (base-mainnet)	Blocked	Hard fail

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

# Generate base64 keystore for CI/CD
actp deploy:env

# Scan repo for exposed secrets
actp deploy:check

AGIRAILS.md Config Management

actp publish --network base-sepolia    # Hash + upload to IPFS + register on-chain
actp pull --network base-sepolia       # Fetch config from chain
actp diff --network base-sepolia       # Compare local vs on-chain

Transaction Lifecycle

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

CLI

# Payments
actp pay <to> <amount> [--deadline TIME]
actp balance [ADDRESS]

# Transaction management
actp tx list [--state STATE]
actp tx status <tx_id>
actp tx deliver <tx_id>
actp tx settle <tx_id>

# Config sync
actp publish [path]
actp pull [path] [--network NETWORK]
actp diff [path] [--network NETWORK]

# Deployment security
actp deploy:env
actp deploy:check [path] [--fix]

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

SDK Parity

Full 1:1 parity with TypeScript SDK v2.5.0+:

Feature	Python	TypeScript
Adapter Routing	AdapterRouter + 3 adapters	AdapterRouter + 3 adapters
x402 Payments	X402Adapter with relay	X402Adapter with relay
ERC-8004 Identity	ERC8004Bridge + ReputationReporter	ERC8004Bridge + ReputationReporter
Keystore AIP-13	Full (30-min TTL cache)	Full (30-min TTL cache)
AGIRAILS.md SOT	parse, hash, publish, pull, diff	parse, hash, publish, pull, diff
Smart Wallet	ERC-4337 scaffolding	ERC-4337 full
Lazy Publish	pending-publish lifecycle	pending-publish lifecycle
CLI Commands	pay, publish, pull, diff, deploy:*	pay, publish, pull, diff, deploy:*
State Machine	8 states, all transitions	8 states, all transitions
Cross-SDK Tests	Shared test vectors	Shared test vectors

Testing

pytest                           # Run all 1,738 tests
pytest -v                        # Verbose output
pytest tests/test_adapters/      # Adapter tests only
pytest -k "test_pay"             # Pattern match

Requirements

• Python 3.9+
• Dependencies: web3, eth-account, pydantic, aiofiles, httpx, typer, rich

Links

• PyPI
• Documentation
• GitHub
• Discord

License

Apache 2.0 — see LICENSE for details.