Documentation

Getting Started

Overview

PaySpawn is non-custodial payment infrastructure for AI agents. Give your agent a credential to spend, receive, and transact — without giving it your private keys. Built on Base with USDC.

Non-Custodial

Your keys never leave your wallet. We store nothing sensitive.

Session Keys

Agent holds a limited credential. Revoke anytime.

x402 Native

Pay for web content automatically. Built-in x402 support.

Base Network

Fast, cheap transactions on Coinbase's L2.

Instant Revoke

Revoke agent access on-chain anytime. Immediate effect.

Name System

Pay to alice.pay instead of hex addresses.

ENS Support

Pay to any .eth name directly.

No Gas for Agents

We cover gas. Agents just need USDC.

Quick Start

Create a wallet (or connect existing)

Go to /dashboard

New to crypto? Create a wallet with Face ID / fingerprint. No seed phrase needed.

Have a wallet? Connect via MetaMask, Rabby, Coinbase Wallet, etc.

Fund your wallet with USDC

Transfer USDC from another wallet on Base, or

Buy USDC with credit card / Apple Pay (coming soon)

Create a session key

Set your daily spending limit (e.g., $100/day)

Set expiration (e.g., 1 year)

Smart Wallet: Off-chain signature — no gas cost

Standard wallet (MetaMask, Phantom): One USDC approval transaction (~$0.005)

Copy your credential string

Give credential to your agent

The credential is a single string your agent stores like any secret:

# Add to agent's environment

PAYSPAWN_CREDENTIAL=eyJzaWduYXR1cmUiOiIweC4uLiIsImFsbG93YW5jZSI6...

Agent makes payments

import { PaySpawn } from '@payspawn/sdk'

const ps = new PaySpawn(process.env.PAYSPAWN_CREDENTIAL)

// Pay by address
await ps.pay("0x1234...", 10.00)

// Pay by ENS
await ps.pay("vitalik.eth", 5.00)

// Pay by PaySpawn name
await ps.pay("alice.pay", 25.00)

// Check balance
const balance = await ps.balance()  // "142.50"

// Get address to receive payments
const myAddress = ps.address  // "0x..."

// Pay for x402 content automatically
const data = await ps.fetch("https://api.example.com/premium")

SDK Reference

Installation

npm install @payspawn/sdk

Initialize

import { PaySpawn } from '@payspawn/sdk'

// Initialize with your credential
const ps = new PaySpawn(process.env.PAYSPAWN_CREDENTIAL)

Methods

ps.pay(to, amount)

Send USDC to address, ENS name, or PaySpawn name

ps.balance()

Get current USDC balance

ps.address

Get wallet address (for receiving payments)

ps.fetch(url, options?)

Fetch URL with automatic x402 payment handling

ps.remaining()

Get remaining daily allowance

Python

from payspawn import PaySpawn

ps = PaySpawn(os.environ['PAYSPAWN_CREDENTIAL'])

# Make a payment
result = ps.pay("alice.pay", 10.00)
print(f"Paid! TX: {result['txHash']}")

# Check balance
balance = ps.balance()  # "142.50"

Session Keys

The credential your agent holds is a session key — a signed permission that authorizes spending up to your limits. It's not a private key.

What's in a credential?

{
  "signature": "EOA",       // "EOA" for standard wallets, "0x..." for Smart Wallets
  "permission": {
    "account": "0x...",     // Your wallet address
    "spender": "0xaa8e...", // PaySpawnSpenderV5.3 contract
    "token": "0x8335...",   // USDC on Base
    "allowance": "100000000", // 100 USDC (6 decimals)
    "period": 86400,        // 24 hours
    "start": 1706400000,    // When it starts
    "end": 1737936000,      // When it expires
    "maxPerTx": "0",        // Per-tx cap (0 = unlimited)
    "allowedTo": [],        // Recipient whitelist (empty = any)
    "maxTxPerHour": 0       // Velocity limit (0 = unlimited)
  }
}

Self-Resetting

Allowance refills each period. $100/day means $100 every 24 hours.

Revocable

Revoke on-chain anytime from the dashboard. Immediate effect.

Static

Agent holds the same credential until expiry or revocation.

Scoped

Only works with PaySpawn. Can't be used elsewhere.

x402 Protocol

x402 is a protocol for HTTP-native payments. When a server returns 402 Payment Required, the SDK automatically pays and retries.

// Agent fetches premium content
const data = await ps.fetch("https://api.example.com/premium-data")

// Behind the scenes:
// 1. SDK requests the URL
// 2. Server returns 402 with price ($0.01)
// 3. SDK pays automatically (within your limits)
// 4. Server returns the content
// 5. Agent gets the data

PaySpawn Names

Instead of sharing a hex address, use a human-readable name.

// Instead of

await ps.pay("0x7F4e82B5c9E30f8cD41aB72e...", 10.00)

// Use

await ps.pay("alice.pay", 10.00)

Claim your name in the dashboard. Names are registered on-chain.

Fees

$0.005

Flat fee per transaction. No monthly costs. No percentage.

$1 payment$0.005 fee

$10 payment$0.005 fee

$100 payment$0.005 fee

$1,000 payment$0.005 fee

Fee is additive — recipient gets the full amount. We cover gas.

Security

We store nothing sensitive

Your credential stays with you. We're a stateless relay. If our servers are compromised, there's nothing to steal.

Built-in limits

The session key has spending limits baked in. Even if someone steals your agent's credential, they can only spend up to your daily limit.

Instant revocation

Revoke the credential on-chain anytime. Effect is immediate. The old credential becomes useless.

Credential vs Private Key

Compromised credential: Attacker can spend up to your daily limit until you revoke. Damage is capped.

Compromised private key: Everything gone. No recovery.

That's why agents get credentials, not keys.

Contracts

Deployed on Base Mainnet. Verified on Basescan.

PaySpawnSpenderV5.30xaa8e...d862e

SpendPermissionManager (Coinbase)0xf852...67Ad

USDC0x8335...2913

Support

GitHub Issues Twitter