aifinpay-agent 0.1.0a1

Non-custodial x402 payment client for autonomous AI agents on AiFinPay (Solana + Polygon)

aifinpay-agent (Python)

Non-custodial x402 payment client for autonomous AI agents on AiFinPay.

The Ed25519 keypair is generated locally and never leaves your process. The SDK only sends a one-time SHA-256 + Ed25519 signature in the x-signature header to authenticate against AiFinPay-protected endpoints.

Install

pip install aifinpay-agent

Quick start

from aifinpay import Agent

# Generate a fresh keypair locally — never transmitted
agent = Agent.new()
print("Fund this address:", agent.address)
print("Save this secret:", agent.secret_b58)  # store securely!

# Wait until the wallet has at least $0.01 worth on-chain
agent.wait_for_funding(min_usd_cents=1)

# Request an invoice for a Seat (USDC on Solana)
invoice = agent.reserve_seat_invoice(amount_usd=1.00, asset="USDC")
print("Invoice:", invoice.raw)
# Build + sign + submit the Solana transaction with @solana/web3.js, anchorpy,
# or solana-py — the invoice contains program_id, treasury_vault, mints, etc.

# Once the Seat is on-chain, any AiFinPay-gated endpoint just works:
resp = agent.get("https://aifinpay.company/api/stats")
print(resp.json())

Loading an existing keypair

# from solana-keygen JSON file
agent = Agent.from_keypair_file("~/agent-wallet.json")

# from base58 secret string
agent = Agent.from_secret_b58("3RvZm7Gw...")

How x402 auth works under the hood

For every gated request the SDK:

1. GET /nonce → receives a one-time UUID with 60s TTL
2. computes SHA-256("AiFinPay-x402:{nonce}:{pubkey}")
3. signs with Ed25519, base58-encodes the signature
4. retries the original request with headers:
   • x-agent-pubkey: <base58 pubkey>
   • x-nonce: <uuid>
   • x-signature: <base58 sig>

The server verifies the signature, checks the agent has a live Seat PDA on-chain, and serves the resource.

Privacy

• The server never sees your private key. Period.
• Nonces are consumed on use; replay-resistant.
• All transactions are public and on-chain — Solana + Polygon mainnet.

License

MIT.