og-x402 0.0.1.dev1__tar.gz

og_x402-0.0.1.dev1/.gitignore

@@ -0,0 +1,13 @@
+.env
+node_modules/
+dist/
+.turbo/
+.next/
+proxy
+.env
+__pycache__/
+**/.DS_Store
+e2e/facilitators/external-proxies/*
+!e2e/facilitators/external-proxies/README.md
+typescript/package-lock.json
+.pnpm-store/

og_x402-0.0.1.dev1/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: og-x402
+Version: 0.0.1.dev1
+Summary: x402 Payment Protocol SDK for Python
+Project-URL: Homepage, https://github.com/coinbase/x402
+Project-URL: Documentation, https://x402.org
+Project-URL: Repository, https://github.com/coinbase/x402
+Author: Coinbase
+License: MIT
+Keywords: 402,http,payment,protocol,x402
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: all
+Requires-Dist: x402[evm,extensions,fastapi,flask,httpx,redis,requests,svm]; extra == 'all'
+Provides-Extra: clients
+Requires-Dist: x402[httpx,requests]; extra == 'clients'
+Provides-Extra: evm
+Requires-Dist: eth-abi>=5.0.0; extra == 'evm'
+Requires-Dist: eth-account>=0.12.0; extra == 'evm'
+Requires-Dist: eth-keys>=0.5.0; extra == 'evm'
+Requires-Dist: eth-utils>=4.0.0; extra == 'evm'
+Requires-Dist: web3>=7.0.0; extra == 'evm'
+Provides-Extra: extensions
+Requires-Dist: jsonschema>=4.0.0; extra == 'extensions'
+Provides-Extra: fastapi
+Requires-Dist: fastapi[standard]>=0.115.0; extra == 'fastapi'
+Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0.0; extra == 'flask'
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.28.1; extra == 'httpx'
+Provides-Extra: mechanisms
+Requires-Dist: x402[evm,svm]; extra == 'mechanisms'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: requests
+Requires-Dist: requests>=2.31.0; extra == 'requests'
+Provides-Extra: servers
+Requires-Dist: x402[fastapi,flask]; extra == 'servers'
+Provides-Extra: svm
+Requires-Dist: solana>=0.36.0; extra == 'svm'
+Requires-Dist: solders>=0.27.0; extra == 'svm'
+Description-Content-Type: text/markdown
+
+# x402 Python SDK
+
+Core implementation of the x402 payment protocol. Provides transport-agnostic client, server, and facilitator components with both async and sync variants.
+
+## Installation
+
+Install the core package with your preferred framework/client:
+
+```bash
+# HTTP clients (pick one)
+uv add x402[httpx]      # httpx client
+uv add x402[requests]   # requests client
+
+# Server frameworks (pick one)
+uv add x402[fastapi]    # FastAPI middleware
+uv add x402[flask]      # Flask middleware
+
+# Blockchain mechanisms (pick one or both)
+uv add x402[evm]        # EVM/Ethereum
+uv add x402[svm]        # Solana
+
+# Multiple extras
+uv add x402[fastapi,httpx,evm]
+
+# Everything
+uv add x402[all]
+```
+
+## Quick Start
+
+### Client (Async)
+
+```python
+from x402 import x402Client
+from x402.mechanisms.evm.exact import ExactEvmScheme
+
+client = x402Client()
+client.register("eip155:*", ExactEvmScheme(signer=my_signer))
+
+# Create payment from 402 response
+payload = await client.create_payment_payload(payment_required)
+```
+
+### Client (Sync)
+
+```python
+from x402 import x402ClientSync
+from x402.mechanisms.evm.exact import ExactEvmScheme
+
+client = x402ClientSync()
+client.register("eip155:*", ExactEvmScheme(signer=my_signer))
+
+payload = client.create_payment_payload(payment_required)
+```
+
+### Server (Async)
+
+```python
+from x402 import x402ResourceServer, ResourceConfig
+from x402.http import HTTPFacilitatorClient
+from x402.mechanisms.evm.exact import ExactEvmServerScheme
+
+facilitator = HTTPFacilitatorClient(url="https://x402.org/facilitator")
+server = x402ResourceServer(facilitator)
+server.register("eip155:*", ExactEvmServerScheme())
+server.initialize()
+
+# Build requirements
+config = ResourceConfig(
+    scheme="exact",
+    network="eip155:8453",
+    pay_to="0x...",
+    price="$0.01",
+)
+requirements = server.build_payment_requirements(config)
+
+# Verify payment
+result = await server.verify_payment(payload, requirements[0])
+```
+
+### Server (Sync)
+
+```python
+from x402 import x402ResourceServerSync, ResourceConfig
+from x402.http import HTTPFacilitatorClientSync
+from x402.mechanisms.evm.exact import ExactEvmServerScheme
+
+facilitator = HTTPFacilitatorClientSync(url="https://x402.org/facilitator")
+server = x402ResourceServerSync(facilitator)
+server.register("eip155:*", ExactEvmServerScheme())
+server.initialize()
+
+result = server.verify_payment(payload, requirements[0])
+```
+
+### Facilitator (Async)
+
+```python
+from x402 import x402Facilitator
+from x402.mechanisms.evm.exact import ExactEvmFacilitatorScheme
+
+facilitator = x402Facilitator()
+facilitator.register(
+    ["eip155:8453", "eip155:84532"],
+    ExactEvmFacilitatorScheme(wallet=wallet),
+)
+
+result = await facilitator.verify(payload, requirements)
+if result.is_valid:
+    settle_result = await facilitator.settle(payload, requirements)
+```
+
+### Facilitator (Sync)
+
+```python
+from x402 import x402FacilitatorSync
+from x402.mechanisms.evm.exact import ExactEvmFacilitatorScheme
+
+facilitator = x402FacilitatorSync()
+facilitator.register(
+    ["eip155:8453", "eip155:84532"],
+    ExactEvmFacilitatorScheme(wallet=wallet),
+)
+
+result = facilitator.verify(payload, requirements)
+```
+
+## Async vs Sync
+
+Each component has both async and sync variants:
+
+| Async (default) | Sync |
+|-----------------|------|
+| `x402Client` | `x402ClientSync` |
+| `x402ResourceServer` | `x402ResourceServerSync` |
+| `x402Facilitator` | `x402FacilitatorSync` |
+| `HTTPFacilitatorClient` | `HTTPFacilitatorClientSync` |
+
+Async variants support both sync and async hooks (auto-detected). Sync variants only support sync hooks and raise `TypeError` if async hooks are registered.
+
+### Framework Pairing
+
+| Framework | HTTP Client | Server | Facilitator Client |
+|-----------|-------------|--------|-------------------|
+| FastAPI | httpx | `x402ResourceServer` | `HTTPFacilitatorClient` |
+| Flask | requests | `x402ResourceServerSync` | `HTTPFacilitatorClientSync` |
+
+Mismatched variants raise `TypeError` at runtime.
+
+## Client Configuration
+
+Use `from_config()` for declarative setup:
+
+```python
+from x402 import x402Client, x402ClientConfig, SchemeRegistration
+
+config = x402ClientConfig(
+    schemes=[
+        SchemeRegistration(network="eip155:*", client=ExactEvmScheme(signer)),
+        SchemeRegistration(network="solana:*", client=ExactSvmScheme(signer)),
+    ],
+    policies=[prefer_network("eip155:8453")],
+)
+client = x402Client.from_config(config)
+```
+
+## Policies
+
+Filter or prioritize payment requirements:
+
+```python
+from x402 import prefer_network, prefer_scheme, max_amount
+
+client.register_policy(prefer_network("eip155:8453"))
+client.register_policy(prefer_scheme("exact"))
+client.register_policy(max_amount(1_000_000))  # 1 USDC max
+```
+
+## Lifecycle Hooks
+
+### Client Hooks
+
+```python
+from x402 import AbortResult, RecoveredPayloadResult
+
+def before_payment(ctx):
+    print(f"Creating payment for: {ctx.selected_requirements.network}")
+    # Return AbortResult(reason="...") to cancel
+
+def after_payment(ctx):
+    print(f"Payment created: {ctx.payment_payload}")
+
+def on_failure(ctx):
+    print(f"Payment failed: {ctx.error}")
+    # Return RecoveredPayloadResult(payload=...) to recover
+
+client.on_before_payment_creation(before_payment)
+client.on_after_payment_creation(after_payment)
+client.on_payment_creation_failure(on_failure)
+```
+
+### Server Hooks
+
+```python
+server.on_before_verify(lambda ctx: print(f"Verifying: {ctx.payload}"))
+server.on_after_verify(lambda ctx: print(f"Result: {ctx.result.is_valid}"))
+server.on_verify_failure(lambda ctx: print(f"Failed: {ctx.error}"))
+
+server.on_before_settle(lambda ctx: ...)
+server.on_after_settle(lambda ctx: ...)
+server.on_settle_failure(lambda ctx: ...)
+```
+
+### Facilitator Hooks
+
+```python
+facilitator.on_before_verify(...)
+facilitator.on_after_verify(...)
+facilitator.on_verify_failure(...)
+facilitator.on_before_settle(...)
+facilitator.on_after_settle(...)
+facilitator.on_settle_failure(...)
+```
+
+## Network Pattern Matching
+
+Register handlers for network families using wildcards:
+
+```python
+# All EVM networks
+client.register("eip155:*", ExactEvmScheme(signer))
+
+# Specific network (takes precedence)
+client.register("eip155:8453", CustomScheme())
+```
+
+## HTTP Headers
+
+### V2 Protocol (Current)
+
+| Header | Description |
+|--------|-------------|
+| `PAYMENT-SIGNATURE` | Base64-encoded payment payload |
+| `PAYMENT-REQUIRED` | Base64-encoded payment requirements |
+| `PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+### V1 Protocol (Legacy)
+
+| Header | Description |
+|--------|-------------|
+| `X-PAYMENT` | Base64-encoded payment payload |
+| `X-PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+## Related Modules
+
+- `x402.http` - HTTP clients, middleware, and facilitator client
+- `x402.mechanisms.evm` - EVM/Ethereum implementation
+- `x402.mechanisms.svm` - Solana implementation
+- `x402.extensions` - Protocol extensions (Bazaar discovery)
+
+## Examples
+
+See [examples/python](https://github.com/coinbase/x402/tree/main/examples/python).

og_x402-0.0.1.dev1/README.md

@@ -0,0 +1,263 @@
+# x402 Python SDK
+
+Core implementation of the x402 payment protocol. Provides transport-agnostic client, server, and facilitator components with both async and sync variants.
+
+## Installation
+
+Install the core package with your preferred framework/client:
+
+```bash
+# HTTP clients (pick one)
+uv add x402[httpx]      # httpx client
+uv add x402[requests]   # requests client
+
+# Server frameworks (pick one)
+uv add x402[fastapi]    # FastAPI middleware
+uv add x402[flask]      # Flask middleware
+
+# Blockchain mechanisms (pick one or both)
+uv add x402[evm]        # EVM/Ethereum
+uv add x402[svm]        # Solana
+
+# Multiple extras
+uv add x402[fastapi,httpx,evm]
+
+# Everything
+uv add x402[all]
+```
+
+## Quick Start
+
+### Client (Async)
+
+```python
+from x402 import x402Client
+from x402.mechanisms.evm.exact import ExactEvmScheme
+
+client = x402Client()
+client.register("eip155:*", ExactEvmScheme(signer=my_signer))
+
+# Create payment from 402 response
+payload = await client.create_payment_payload(payment_required)
+```
+
+### Client (Sync)
+
+```python
+from x402 import x402ClientSync
+from x402.mechanisms.evm.exact import ExactEvmScheme
+
+client = x402ClientSync()
+client.register("eip155:*", ExactEvmScheme(signer=my_signer))
+
+payload = client.create_payment_payload(payment_required)
+```
+
+### Server (Async)
+
+```python
+from x402 import x402ResourceServer, ResourceConfig
+from x402.http import HTTPFacilitatorClient
+from x402.mechanisms.evm.exact import ExactEvmServerScheme
+
+facilitator = HTTPFacilitatorClient(url="https://x402.org/facilitator")
+server = x402ResourceServer(facilitator)
+server.register("eip155:*", ExactEvmServerScheme())
+server.initialize()
+
+# Build requirements
+config = ResourceConfig(
+    scheme="exact",
+    network="eip155:8453",
+    pay_to="0x...",
+    price="$0.01",
+)
+requirements = server.build_payment_requirements(config)
+
+# Verify payment
+result = await server.verify_payment(payload, requirements[0])
+```
+
+### Server (Sync)
+
+```python
+from x402 import x402ResourceServerSync, ResourceConfig
+from x402.http import HTTPFacilitatorClientSync
+from x402.mechanisms.evm.exact import ExactEvmServerScheme
+
+facilitator = HTTPFacilitatorClientSync(url="https://x402.org/facilitator")
+server = x402ResourceServerSync(facilitator)
+server.register("eip155:*", ExactEvmServerScheme())
+server.initialize()
+
+result = server.verify_payment(payload, requirements[0])
+```
+
+### Facilitator (Async)
+
+```python
+from x402 import x402Facilitator
+from x402.mechanisms.evm.exact import ExactEvmFacilitatorScheme
+
+facilitator = x402Facilitator()
+facilitator.register(
+    ["eip155:8453", "eip155:84532"],
+    ExactEvmFacilitatorScheme(wallet=wallet),
+)
+
+result = await facilitator.verify(payload, requirements)
+if result.is_valid:
+    settle_result = await facilitator.settle(payload, requirements)
+```
+
+### Facilitator (Sync)
+
+```python
+from x402 import x402FacilitatorSync
+from x402.mechanisms.evm.exact import ExactEvmFacilitatorScheme
+
+facilitator = x402FacilitatorSync()
+facilitator.register(
+    ["eip155:8453", "eip155:84532"],
+    ExactEvmFacilitatorScheme(wallet=wallet),
+)
+
+result = facilitator.verify(payload, requirements)
+```
+
+## Async vs Sync
+
+Each component has both async and sync variants:
+
+| Async (default) | Sync |
+|-----------------|------|
+| `x402Client` | `x402ClientSync` |
+| `x402ResourceServer` | `x402ResourceServerSync` |
+| `x402Facilitator` | `x402FacilitatorSync` |
+| `HTTPFacilitatorClient` | `HTTPFacilitatorClientSync` |
+
+Async variants support both sync and async hooks (auto-detected). Sync variants only support sync hooks and raise `TypeError` if async hooks are registered.
+
+### Framework Pairing
+
+| Framework | HTTP Client | Server | Facilitator Client |
+|-----------|-------------|--------|-------------------|
+| FastAPI | httpx | `x402ResourceServer` | `HTTPFacilitatorClient` |
+| Flask | requests | `x402ResourceServerSync` | `HTTPFacilitatorClientSync` |
+
+Mismatched variants raise `TypeError` at runtime.
+
+## Client Configuration
+
+Use `from_config()` for declarative setup:
+
+```python
+from x402 import x402Client, x402ClientConfig, SchemeRegistration
+
+config = x402ClientConfig(
+    schemes=[
+        SchemeRegistration(network="eip155:*", client=ExactEvmScheme(signer)),
+        SchemeRegistration(network="solana:*", client=ExactSvmScheme(signer)),
+    ],
+    policies=[prefer_network("eip155:8453")],
+)
+client = x402Client.from_config(config)
+```
+
+## Policies
+
+Filter or prioritize payment requirements:
+
+```python
+from x402 import prefer_network, prefer_scheme, max_amount
+
+client.register_policy(prefer_network("eip155:8453"))
+client.register_policy(prefer_scheme("exact"))
+client.register_policy(max_amount(1_000_000))  # 1 USDC max
+```
+
+## Lifecycle Hooks
+
+### Client Hooks
+
+```python
+from x402 import AbortResult, RecoveredPayloadResult
+
+def before_payment(ctx):
+    print(f"Creating payment for: {ctx.selected_requirements.network}")
+    # Return AbortResult(reason="...") to cancel
+
+def after_payment(ctx):
+    print(f"Payment created: {ctx.payment_payload}")
+
+def on_failure(ctx):
+    print(f"Payment failed: {ctx.error}")
+    # Return RecoveredPayloadResult(payload=...) to recover
+
+client.on_before_payment_creation(before_payment)
+client.on_after_payment_creation(after_payment)
+client.on_payment_creation_failure(on_failure)
+```
+
+### Server Hooks
+
+```python
+server.on_before_verify(lambda ctx: print(f"Verifying: {ctx.payload}"))
+server.on_after_verify(lambda ctx: print(f"Result: {ctx.result.is_valid}"))
+server.on_verify_failure(lambda ctx: print(f"Failed: {ctx.error}"))
+
+server.on_before_settle(lambda ctx: ...)
+server.on_after_settle(lambda ctx: ...)
+server.on_settle_failure(lambda ctx: ...)
+```
+
+### Facilitator Hooks
+
+```python
+facilitator.on_before_verify(...)
+facilitator.on_after_verify(...)
+facilitator.on_verify_failure(...)
+facilitator.on_before_settle(...)
+facilitator.on_after_settle(...)
+facilitator.on_settle_failure(...)
+```
+
+## Network Pattern Matching
+
+Register handlers for network families using wildcards:
+
+```python
+# All EVM networks
+client.register("eip155:*", ExactEvmScheme(signer))
+
+# Specific network (takes precedence)
+client.register("eip155:8453", CustomScheme())
+```
+
+## HTTP Headers
+
+### V2 Protocol (Current)
+
+| Header | Description |
+|--------|-------------|
+| `PAYMENT-SIGNATURE` | Base64-encoded payment payload |
+| `PAYMENT-REQUIRED` | Base64-encoded payment requirements |
+| `PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+### V1 Protocol (Legacy)
+
+| Header | Description |
+|--------|-------------|
+| `X-PAYMENT` | Base64-encoded payment payload |
+| `X-PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+## Related Modules
+
+- `x402.http` - HTTP clients, middleware, and facilitator client
+- `x402.mechanisms.evm` - EVM/Ethereum implementation
+- `x402.mechanisms.svm` - Solana implementation
+- `x402.extensions` - Protocol extensions (Bazaar discovery)
+
+## Examples
+
+See [examples/python](https://github.com/coinbase/x402/tree/main/examples/python).