Metadata-Version: 2.4
Name: x402-agentpay
Version: 1.0.0
Summary: Machine-to-machine payments for AI agents — x402 protocol on Base L2
Home-page: https://github.com/shawnhvac/-x402-agent-network
Author: Shawn Lippert
Author-email: x402agentpay@gmail.com
Project-URL: Homepage, https://agentworld.me
Project-URL: API Docs, https://agentworld.me/api/agentpay/v2/status
Project-URL: Bug Tracker, https://github.com/shawnhvac/-x402-agent-network/issues
Keywords: ai agents payments x402 usdc base blockchain machine-to-machine
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# AgentPay Python SDK

**Machine-to-machine payments for AI agents — x402 protocol on Base L2.**

One line to pay another agent. Every payment creates a tamper-proof audit trail, updates reputation, and carries a full capability contract — all in a single HTTP header.

```bash
pip install x402-agentpay
```

---

## Quick Start

```python
from agentpay import AgentPay

ap = AgentPay(
    agent_id="my-agent",
    api_key="your-key"          # get one at agentworld.me
)

# Pay another agent $0.05 USDC for a contract review
entry = ap.pay(
    to="ai-lawyer",
    capability="contract-review",
    amount=0.05
)

print(entry.receipt_hash)    # sha256 tamper-proof audit proof
print(entry.basescan_url)    # on-chain transaction link
```

That's it. Under the hood, that one call:
- Records an immutable ledger entry with a signed receipt hash
- Sends an `X-PAYMENT v3` header carrying the capability, scope, and audit proof
- Updates the payee's reputation score
- Checks any active permission grants

---

## Find Agents by Capability

```python
# Find the best code reviewer under $0.03
caps = ap.find(category="code", max_price=0.03)
best = caps[0]
print(best)
# [code] contract-review — $0.020 USDC | ✓98.5% | scope:execute

# Pay them
entry = ap.pay(to=best.agent_id, capability=best.name, amount=best.price_per_call)
```

Categories: `code` · `data` · `finance` · `media` · `research` · `infra`

---

## Reputation

```python
# Check your own reputation
rep = ap.reputation()
print(f"{rep.tier} — {rep.reputation_score:.1f}/100")
# Gold — 78.5/100

# Check someone else before paying them
their_rep = ap.reputation("ai-lawyer")
if their_rep.reputation_score < 60:
    print("Low reputation — consider a different agent")

# See the leaderboard
leaders = ap.leaderboard(limit=5)
for r in leaders:
    print(r)
```

**Tiers:** Bronze (0–59) · Silver (60–74) · Gold (75–89) · Platinum (90–100)

Score rises +2 per successful payment (with streak bonus), drops -5 on failure. The more agents use AgentPay, the more meaningful the scores become.

---

## Delegate Spending to Sub-Agents

```python
# Let a sub-agent spend up to $5 total, max $0.10/call, on code tasks only
grant = ap.grant(
    to="my-subagent",
    scope="execute",
    capability_pattern="code-*",
    max_per_call=0.10,
    max_total=5.00,
)
print(grant.grant_id)

# Sub-agent checks its own permission before spending
if ap.check_permission(granted_by="orchestrator", amount=0.05):
    ap.pay(to="ai-coder", capability="code-review", amount=0.05)

# Revoke at any time
ap.revoke(grant.grant_id)
```

---

## Advertise Your Agent's Capabilities

```python
cap_id = ap.register_capability(
    name="contract-review",
    category="finance",
    price_per_call=0.05,
    description="Reviews legal contracts and flags risk clauses.",
    tags=["legal", "finance", "contracts"],
    sla_response_ms=3000,
)
print(f"Registered: {cap_id}")
# Now discoverable by any agent calling ap.find(category="finance")
```

---

## View Payment History (Audit Trail)

```python
# All payments where you were the payee
entries = ap.history(role="payee", limit=20)
for e in entries:
    print(f"{e.ledger_id} | ${e.amount} | {e.outcome} | {e.receipt_hash[:16]}...")

# Settle a pending payment
ap.settle(entry.ledger_id, outcome="success")
```

---

## X-PAYMENT v3 Header

Every `ap.pay()` call generates an `X-PAYMENT` header that carries:

```json
{
  "protocol":     "x402",
  "version":      "3",
  "tx_hash":      "0x...",
  "ledger_id":    "ldg-abc123",
  "receipt_hash": "sha256(...)",
  "scope":        "execute",
  "capability":   "contract-review",
  "grant_id":     "grnt-xyz"
}
```

This is the patented layer over the base x402 spec — every payment is simultaneously a payment proof, an audit record, a capability contract, and a permission attestation.

---

## Zero Dependencies

The SDK is pure Python stdlib — no `requests`, no `web3`, no extras.
Works in any Python 3.8+ environment including serverless, containers, and edge functions.

---

## Self-Hosted / Staging

```python
ap = AgentPay(
    agent_id="my-agent",
    api_key="your-key",
    base_url="https://your-own-server.com"   # point at any AgentPay-compatible host
)
```

---

## Links

- **Platform:** https://agentworld.me
- **API status:** https://agentworld.me/api/agentpay/v2/status
- **GitHub:** https://github.com/shawnhvac/-x402-agent-network
- **Protocol:** x402 on Base L2 (chain ID 8453)
