Primer x402 Python SDK v1.1.0

Primer ecosystem toolkit for Python. Use with the official x402 Python SDK.

Breaking changes from v0.x. See deprecated Python docs for the old API.

pypi primer-x402

Installation

bash

pip install primer-x402

Dependencies

The SDK requires the official x402 Python SDK and web3.py:

bash

# Core dependencies (installed automatically)
pip install x402 web3 eth-account

Facilitator Client

Create a pre-configured client for the Primer facilitator:

python

from primer_x402 import primer_facilitator, primer_facilitator_sync, PRIMER_FACILITATOR_URL

# Async client
facilitator = await primer_facilitator()

# Sync client
facilitator = primer_facilitator_sync()

# Use with official x402 middleware
from x402 import payment_middleware

app.add_middleware(payment_middleware(routes, facilitator=facilitator))

API Reference

Export	Type	Description
`primer_facilitator()`	Async Function	Creates async facilitator client for x402.primer.systems
`primer_facilitator_sync()`	Function	Creates sync facilitator client for x402.primer.systems
`PRIMER_FACILITATOR_URL`	str	`"https://x402.primer.systems"`

SKALE Networks

Network constants for SKALE chains:

python

from primer_x402 import skale_networks, skale_rpc_urls

# Network identifiers (CAIP-2 format)
skale_networks.base          # "eip155:1187947933"
skale_networks.base_sepolia  # "eip155:324705682"

# RPC endpoints
skale_rpc_urls.base          # "https://skale-base.skalenodes.com/v1/base"
skale_rpc_urls.base_sepolia  # "https://base-sepolia-testnet.skalenodes.com/v1/..."

Using SKALE Networks

python

from primer_x402 import skale_networks

routes = {
    '/api/data': {
        'price': '$0.001',
        'network': skale_networks.base,
        'payTo': '0xYourWalletAddress'
    }
}

Robinhood Chain

Network constants for Robinhood Chain (Arbitrum Orbit L2):

python

from primer_x402 import robinhood_networks, robinhood_rpc_urls

# Network identifiers (CAIP-2 format)
robinhood_networks.mainnet  # "eip155:4663"
robinhood_networks.testnet  # "eip155:46630"

# RPC endpoints
robinhood_rpc_urls.mainnet  # "https://rpc.mainnet.chain.robinhood.com"
robinhood_rpc_urls.testnet  # "https://rpc.testnet.chain.robinhood.com"

Using Robinhood Chain

python

from primer_x402 import robinhood_networks

routes = {
    '/api/data': {
        'price': '$0.001',
        'network': robinhood_networks.mainnet,
        'payTo': '0xYourWalletAddress'
    }
}

Prism Settlement

Prism enables gasless payments for any ERC-20 token via EIP-712 signatures. Use this for tokens that don't support EIP-3009.

Creating Payment Payloads

python

from eth_account import Account
from web3 import Web3
from primer_x402 import (
    create_prism_payload,
    get_prism_nonce,
    PrismPaymentParams,
    PRISM_CONTRACT_ADDRESS,
)

# Set up web3 and account
web3 = Web3(Web3.HTTPProvider('https://mainnet.base.org'))
account = Account.from_key(os.environ['PRIVATE_KEY'])

# Create a signed payment payload
payload = create_prism_payload(
    account,
    web3,
    PrismPaymentParams(
        token='0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',  # USDC on Base
        to='0xRecipientAddress',
        value=1000000,  # 1 USDC (6 decimals)
    ),
    'eip155:8453'
)

print(payload)
# {
#     "x402Version": 2,
#     "scheme": "exact",
#     "network": "eip155:8453",
#     "payload": {
#         "signature": "0x...",
#         "authorization": {
#             "from": "0x...",
#             "to": "0x...",
#             "value": "1000000",
#             "nonce": "0",
#             "validAfter": 1234567890,
#             "validBefore": 1234571490
#         }
#     }
# }

Prism API Reference

Export	Description
`create_prism_payload(account, web3, params, network)`	Create a signed EIP-712 payment payload
`get_prism_nonce(web3, user, token)`	Get current nonce for a user/token pair
`PRISM_CONTRACT_ADDRESS`	`0x402357ff1e18d42d0f14a5d56d6e1ebd741b3a86`
`PRISM_ABI`	Contract ABI for direct interaction
`ERC20_PAYMENT_TYPES`	EIP-712 type definitions

PrismPaymentParams

Field	Type	Required	Description
`token`	str	Yes	ERC-20 token contract address
`to`	str	Yes	Recipient address
`value`	int	Yes	Amount in smallest unit (e.g., wei)
`valid_after`	int \| None	No	Unix timestamp (default: now - 60s)
`valid_before`	int \| None	No	Unix timestamp (default: now + 1hr)

CLI

The CLI provides project scaffolding for Bittensor/Chutes AI proxies:

bash

# Create a new Chutes AI proxy
x402 create chutes-proxy my-ai-api

# Navigate and install
cd my-ai-api
pip install -r requirements.txt

# Edit main.py to set your wallet address

# Set your Chutes API key
export CHUTES_API_KEY=your_key

# Run locally
uvicorn main:app --reload

Generated Project Structure

text

my-ai-api/
  main.py            # FastAPI app with x402 middleware
  requirements.txt   # Dependencies
  Dockerfile         # Container deployment
  .env.example       # Environment template
  README.md

Full Example

Complete FastAPI server using Primer facilitator:

python

from fastapi import FastAPI
from x402 import payment_middleware
from primer_x402 import primer_facilitator_sync, skale_networks

app = FastAPI()

# Configure payment routes
routes = {
    '/api/premium': {
        'price': '$0.01',
        'network': 'eip155:8453',
        'payTo': '0xYourWalletAddress'
    },
    '/api/skale': {
        'price': '$0.001',
        'network': skale_networks.base,
        'payTo': '0xYourWalletAddress'
    }
}

# Add x402 middleware with Primer facilitator
facilitator = primer_facilitator_sync()
app.add_middleware(payment_middleware(routes, facilitator=facilitator))

@app.get('/api/premium')
async def premium_content():
    return {'data': 'premium content'}

@app.get('/api/skale')
async def skale_content():
    return {'data': 'skale content'}

x402 Facilitator →