Understand the key concepts behind AgnicPay - X402, wallets, tokens, and payment flows.

Core Concepts

Before diving into the API, it helps to understand the key concepts that power AgnicPay.

The X402 Protocol

X402 is a proposed HTTP status code (like 404 for "Not Found") that means "Payment Required". When an API returns 402, it includes payment instructions that tell the client how to pay for access.

How X402 Works

┌─────────┐                    ┌─────────┐                    ┌─────────┐
│  Your   │  1. Request data   │ X402    │                    │ Agnic   │
│  App    │ ────────────────>  │  API    │                    │  Pay    │
│         │                    │         │                    │         │
│         │  2. 402 + payment  │         │                    │         │
│         │ <───────────────── │         │                    │         │
│         │                    │         │                    │         │
│         │  3. Sign payment   │         │                    │         │
│         │ ────────────────────────────────────────────────> │         │
│         │                    │         │                    │         │
│         │  4. Payment proof  │         │                    │         │
│         │ <──────────────────────────────────────────────── │         │
│         │                    │         │                    │         │
│         │  5. Request + proof│         │                    │         │
│         │ ────────────────>  │         │                    │         │
│         │                    │         │                    │         │
│         │  6. 200 OK + data  │         │                    │         │
│         │ <───────────────── │         │                    │         │
└─────────┘                    └─────────┘                    └─────────┘

Why X402?

Traditional APIs	X402 APIs
Sign up for each service	One wallet for all APIs
Manage multiple API keys	Pay-per-use, no subscriptions
Monthly billing cycles	Instant micropayments
Manual approval needed	Automated payments

Payment Schemes

AgnicPay supports two X402 payment schemes:

Exact Scheme (EIP-3009)

How it works: TransferWithAuthorization - funds transfer exactly on use
Best for: One-time payments, precise billing
Chains: Base (EVM), Solana

Upto Scheme (EIP-2612)

How it works: Permit - pre-authorize up to an amount
Best for: Streaming responses, variable costs
Chains: Base (EVM)

AgnicPay automatically detects and handles both schemes.

Wallets

Embedded Wallets

When you sign up, AgnicPay creates an embedded wallet for you using Privy. This wallet:

Is non-custodial (you control the keys)
Works on Base and Solana
Holds USDC for payments
Supports delegation for automated signing

Delegation (Session Signers)

To enable automated payments, you delegate signing authority to AgnicPay:

You set spending limits (per-transaction, daily, monthly)
You sign a delegation message
AgnicPay can sign payments within your limits
You can revoke access anytime

Delegation never gives AgnicPay access to your full balance - only the ability to sign payments within your specified limits.

API Tokens

API tokens authenticate requests to AgnicPay. Each token has:

Property	Description
`maxPerTransaction`	Maximum USD per single payment
`dailyLimit`	Total USD allowed per 24 hours
`monthlyLimit`	Total USD allowed per 30 days
`networks`	Allowed networks (Base, Solana)
`label`	Your custom label

Token Types

Prefix	Type	Use Case
`agnic_tok_`	API Token	Direct API access
`agnic_at_`	OAuth Access Token	User-authorized apps
`agnic_rt_`	OAuth Refresh Token	Refresh access tokens

Spending Limits

Spending limits protect you from unexpected charges:

Per-Transaction Limit: $1.00
├── Blocks any single payment > $1.00
└── Useful for capping AI response costs

Daily Limit: $10.00
├── Resets every 24 hours
└── Prevents runaway automation

Monthly Limit: $50.00
├── Resets every 30 days
└── Budget control for long-term use

Networks

AgnicPay supports multiple blockchain networks:

Network	Token	Use Case
Base (Mainnet)	USDC	Production payments
Base Sepolia	USDC (testnet)	Development/testing
Solana	USDC	Production payments
Solana Devnet	USDC (devnet)	Development/testing

OAuth tokens are restricted to mainnet networks only (Base, Solana). API tokens can access testnets.

Credits

New users receive $5 in free credits. Credits are used before your wallet balance and:

Core Concepts

Core Concepts

The X402 Protocol

How X402 Works

Why X402?

Payment Schemes

Exact Scheme (EIP-3009)

Upto Scheme (EIP-2612)

Wallets

Embedded Wallets

Delegation (Session Signers)

API Tokens

Token Types

Spending Limits

Networks

Credits

Next Steps

Quickstart

X402 Fetch

API Reference

On this page