Overview

SkillBoss supports two machine payment protocols for AI agents:

x402: Crypto Payments

x402 is Coinbase's protocol for pay-per-call APIs using the HTTP 402 status code.

How It Works

1. Agent sends API request (no auth header)
         ↓
2. Server returns 402 with price quote
         ↓
3. Agent signs payment with crypto wallet
         ↓
4. Agent retries with payment-signature header
         ↓
5. Server verifies payment, executes request
         ↓
6. Server settles payment, returns response

Three-Party Model

• Client (Agent): Pays for API calls with USDC
• Server (SkillBoss): Provides the API, receives payment
• Facilitator (Coinbase): Verifies signatures, settles payments

Request Flow

Step 1: Price Discovery

curl -X POST https://api.heybossai.com/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replicate/flux-1.1-pro",
    "inputs": {"prompt": "A cat astronaut"}
  }'

# Response: 402 Payment Required
# {
#   "error": "Payment required",
#   "price_usd": 0.04,
#   "network": "eip155:8453",
#   "accepts": [{
#     "scheme": "exact",
#     "network": "eip155:8453",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#     "amount": "40000",
#     "payTo": "0x..."
#   }]
# }

Step 2: Sign & Pay

from x402.client import X402Client

client = X402Client(
    wallet_address="0x...",
    private_key="0x...",
    network="base"
)

response = client.post(
    "https://api.heybossai.com/v1/run",
    json={
        "model": "replicate/flux-1.1-pro",
        "inputs": {"prompt": "A cat astronaut"}
    }
)

# Client automatically:
# 1. Receives 402 with price
# 2. Signs payment
# 3. Retries with payment-signature header
# 4. Returns successful response

Supported Networks

Compatible Models

x402 requires deterministic pricing (cost known before execution):

Testing with Testnet

Use Base Sepolia for development:

from x402.client import X402Client

# Testnet client
client = X402Client(
    wallet_address="0x...",
    private_key="0x...",
    network="base-sepolia"  # Testnet
)

# Get testnet USDC from faucet:
# https://www.coinbase.com/faucets/base-sepolia

MPP: Stripe Payments

MPP (Machine Payments Protocol) is an open standard from Stripe and Tempo that enables credit card payments for AI agents using Shared Payment Tokens (SPTs).

How It Works

1. Agent sends API request (no auth header)
         ↓
2. Server returns 402 with Stripe payment challenge
         ↓
3. Agent creates SPT via Stripe API
         ↓
4. Agent retries with Authorization: Payment header
         ↓
5. Server creates PaymentIntent, charges card
         ↓
6. Server executes request, returns response + receipt

Supported Payment Methods

Request Flow

Step 1: Price Discovery

curl -X POST https://api.heybossai.com/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replicate/flux-1.1-pro",
    "inputs": {"prompt": "A cat astronaut"}
  }'

# Response: 402 Payment Required
# {
#   "error": "Payment required",
#   "price_usd": 0.04,
#   "currency": "USD",
#   "methods": ["stripe"],
#   "stripe": {
#     "payment_method_types": ["card", "link"]
#   }
# }
# Header: WWW-Authenticate: Payment realm="heyboss-api", amount="0.04", currency="USD"

Step 2: Create SPT & Pay

import stripe
import base64
import json
import httpx

# Create Shared Payment Token
stripe.api_key = "sk_..."
spt = stripe.PaymentMethod.create_shared_token(
    payment_method="pm_...",  # Customer's payment method
    amount=4,  # Amount in cents
    currency="usd",
)

# Build credential
credential = {
    "type": "stripe",
    "spt": spt.id,
    "amount": "0.04",
    "currency": "USD",
}

# Retry request with payment credential
response = httpx.post(
    "https://api.heybossai.com/v1/run",
    headers={
        "Authorization": f"Payment {base64.b64encode(json.dumps(credential).encode()).decode()}",
        "Content-Type": "application/json",
    },
    json={
        "model": "replicate/flux-1.1-pro",
        "inputs": {"prompt": "A cat astronaut"}
    }
)

# Response includes receipt in payment-receipt header

MPP vs x402

Compatible Models

Both x402 and MPP require deterministic pricing:

Wallet Setup

For x402 (Crypto)

from eth_account import Account

# Create a new wallet
account = Account.create()
print(f"Address: {account.address}")
print(f"Private key: {account.key.hex()}")

# Fund with USDC on Base
# Get testnet USDC from: https://www.coinbase.com/faucets/base-sepolia

For MPP (Stripe)

No wallet needed! MPP uses Stripe's Shared Payment Tokens:

1. Agent has access to a Stripe payment method (card, Link, etc.)
2. Agent creates SPT with spending limits
3. SPT is used for payment credential

Pricing Examples

Image Generation (Per-request)

Model: replicate/flux-1.1-pro
Pricing: $0.04 per image
x402/MPP Compatible: ✅

Payment flow:
1. Request image → 402 (price: $0.04)
2. Sign payment (x402) or create SPT (MPP)
3. Retry with payment header
4. Receive image + receipt

Text-to-Speech (Per-character)

Model: elevenlabs/multilingual-v2
Pricing: $0.00003 per character
x402/MPP Compatible: ✅

Payment flow:
1. Request TTS for "Hello world" (11 chars)
2. Price = 11 * $0.00003 = $0.00033
3. Sign and pay
4. Receive audio + receipt

Video Generation (Per-second)

Model: replicate/minimax-video
Pricing: $0.05 per second
x402/MPP Compatible: ✅

Payment flow:
1. Request 5-second video
2. Price = 5 * $0.05 = $0.25
3. Sign and pay
4. Receive video + receipt

Error Handling

Common Errors

Fallback to API Key

If x402/MPP fails, fall back to traditional API key auth:

try:
    # Try x402/MPP payment
    response = client.post(url, json=data)
except PaymentError:
    # Fall back to API key
    response = requests.post(
        url,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=data
    )

Security

Best Practices

Wallet Security

import os

# Good: Load from environment
private_key = os.environ["AGENT_WALLET_KEY"]

# Bad: Hardcoded
private_key = "0x123..."  # NEVER DO THIS

Integration Guide

With x402 (Crypto)

# pip install x402
from x402.client import X402Client
import os

client = X402Client(
    wallet_address=os.environ["WALLET_ADDRESS"],
    private_key=os.environ["WALLET_KEY"],
    network="base"
)

response = client.post(
    "https://api.heybossai.com/v1/run",
    json={
        "model": "replicate/flux-1.1-pro",
        "inputs": {"prompt": "A sunset over mountains"}
    }
)

With MPP (Stripe)

# pip install pympp stripe
from mpp.client import MppClient
import os

client = MppClient(
    stripe_key=os.environ["STRIPE_SECRET_KEY"],
    payment_method=os.environ["PAYMENT_METHOD_ID"],
)

response = client.post(
    "https://api.heybossai.com/v1/run",
    json={
        "model": "replicate/flux-1.1-pro",
        "inputs": {"prompt": "A sunset over mountains"}
    }
)

Resources

Next Steps