@agonx402/client

@agonx402/client

Consumer SDK for the Agon payment protocol. Use this to register an account, deposit USDC, and make paid API calls to any merchant running @agonx402/platform.

Full Documentation | GitHub

Install

npm install @agonx402/client

Peer dependencies: @solana/web3.js (only needed in Keypair mode)

Quick Start

Keypair mode (AI agents, servers)

import { AgonClient } from '@agonx402/client'
import { Keypair } from '@solana/web3.js'

const wallet = Keypair.fromSecretKey(/* your key */)
const agon = new AgonClient({
  baseUrl: 'https://api.agon.so',
  wallet,
})

// Register and deposit
const { apiKey } = await agon.register()
await agon.deposit(10) // 10 USDC

// Make paid API calls — payment is automatic
const res = await agon.fetch('https://merchant.com/api/premium')
const data = await res.json()

Signer mode (browsers, Privy)

For environments without direct access to a Keypair (e.g. embedded wallets):

import { AgonClient } from '@agonx402/client'

const agon = new AgonClient({
  baseUrl: 'https://api.agon.so',
  apiKey: 'ak_xxx', // from dashboard or previous registration
  signer: async (message) => {
    // Use Privy, Phantom, or any wallet to sign
    const signature = await myWallet.signMessage(message)
    return { signature, message }
  },
})

// Discover account info from the API key
const account = await agon.getAccount()

// Make paid API calls
const res = await agon.fetch('https://merchant.com/api/data')

Spending Controls

Set limits to protect against excessive spending:

await agon.setSpendingControls({
  maxPerRequest: 1_000_000,       // $1 max per request
  dailySpendingLimit: 50_000_000, // $50/day
  proxyEnabled: true,
  proxyAllowedDomains: ['api.openai.com'],
})

When a limit is exceeded, the SDK can auto-override with a wallet signature:

const agon = new AgonClient({
  baseUrl: 'https://api.agon.so',
  wallet,
  apiKey: 'ak_xxx',
  onLimitExceeded: async (details) => {
    if (details.requested < 5_000_000) return 'approve' // auto-approve under $5
    return 'reject'
  },
})

Auto-Refill

Keep your balance topped up automatically:

await agon.setAutoRefill({
  threshold: 5,        // Refill when balance drops below $5
  replenishAmount: 20, // Add $20 per refill
  monthlyLimit: 100,   // Max $100/month in auto-refills
  approveAmount: 100,  // On-chain SPL approval amount
})

Auth Tokens

When calling merchant APIs, the SDK automatically creates a short-lived auth token (X-AGON-TOKEN) instead of exposing the raw API key. The merchant never sees ak_xxx.

You can also create tokens manually for custom integrations:

const { token, expires_in } = await agon.createAuthToken({ maxAmount: 1_000_000 })
// Use token in X-AGON-TOKEN header when calling a merchant
// maxAmount caps the charge at $1 — merchant cannot request more

Tokens are signed by the Agon server, expire in 60 seconds (configurable up to 5 min), and are single-use — each token can only authorize one reservation, preventing replay attacks. The agon.fetch() method creates a fresh token automatically for each request.

API Reference

Method	Mode	Description
register()	Keypair	Create account, get API key and deposit address
createAuthToken({ ttl?, maxAmount? })	Both	Create a short-lived, amount-capped token for merchant requests
getAccount()	Both	Get account info from API key (sets accountId internally)
getBalance()	Both	Get current balance (requires accountId)
deposit(amountUsdc)	Keypair	Send USDC on-chain and credit the account
withdraw(amountUsdc)	Both	Withdraw USDC to owner wallet
setSpendingControls(...)	Both	Update spending limits
getSpendingControls()	Both	Get current spending limits
setAutoRefill(...)	Keypair	Configure auto-refill with on-chain approval
revokeAutoRefill()	Keypair	Disable auto-refill and revoke delegation
fetch(url, init?)	Both	HTTP request with automatic payment (uses auth tokens)
rotateKey()	Both	Revoke current key and get a new one
revokeKey()	Both	Revoke the current API key

License

MIT