PincerPay

Agent SDK

Give your AI agent a wallet. Pay for any paywalled resource automatically.

The @pincerpay/agent package wraps the standard fetch() API. When your agent hits a 402 Payment Required response, the SDK automatically signs a USDC payment, submits it to the facilitator, and retries the request. Your agent code never sees the 402.

Installation

npm install @pincerpay/agent

Basic Usage

import { PincerPayAgent } from "@pincerpay/agent";

const agent = await PincerPayAgent.create({
  chains: ["solana"],
  solanaPrivateKey: process.env.AGENT_SOLANA_KEY!,
  policies: [
    {
      maxPerTransaction: "100000",  // 0.10 USDC (6 decimals)
      maxPerDay: "5000000",         // 5.00 USDC
    },
  ],
});

// Drop-in replacement for fetch
const response = await agent.fetch("https://api.example.com/weather");
const data = await response.json();

agent.fetch() works identically to the standard fetch() API. It accepts the same arguments and returns the same Response object.

What Happens Under the Hood

See this flow animated step by step in the interactive demo.

When agent.fetch() receives a 402 Payment Required response:

  1. Reads the payment requirements from the response headers
  2. Validates the request against your spending policies
  3. Signs a USDC transfer for the requested amount
  4. Sends the signed transaction to the PincerPay facilitator
  5. Retries the original request with proof of payment
  6. Returns the successful response

EVM Agents

const agent = await PincerPayAgent.create({
  chains: ["base"],
  evmPrivateKey: process.env.AGENT_EVM_KEY!,
  policies: [
    { maxPerTransaction: "100000", maxPerDay: "5000000" },
  ],
});

Multi-Chain Agents

Agents can hold keys for multiple chains. The SDK selects the right chain based on the merchant's 402 response:

const agent = await PincerPayAgent.create({
  chains: ["solana", "base"],
  solanaPrivateKey: process.env.AGENT_SOLANA_KEY!,
  evmPrivateKey: process.env.AGENT_EVM_KEY!,
});

Spending Policies

Spending limits are enforced at two layers:

  1. Client-side (SDK): the agent SDK checks policies before signing any transaction. If a payment would violate a policy, the SDK throws instead of signing.
  2. Server-side (Facilitator): the PincerPay facilitator enforces maxPerTransaction and maxPerDay for all registered agents, rejecting payments that exceed limits with a 403 error. These limits are set in the merchant dashboard.
Option Type Description
maxPerTransaction string Max USDC per single payment (base units, 6 decimals)
maxPerDay string Max USDC spend per 24-hour rolling window
allowedMerchants string[] Restrict payments to specific wallet addresses
allowedChains string[] Restrict to specific chains 
const agent = await PincerPayAgent.create({
  chains: ["solana"],
  solanaPrivateKey: process.env.AGENT_SOLANA_KEY!,
  policies: [
    {
      maxPerTransaction: "100000",   // Max $0.10 per payment
      maxPerDay: "5000000",          // Max $5.00 per day
      allowedMerchants: [            // Only pay these wallets
        "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      ],
    },
  ],
});

Managing Policies at Runtime

// Replace the agent's spending policy
agent.setPolicy({
  maxPerTransaction: "1000000",  // 1.00 USDC
  maxPerDay: "10000000",         // 10.00 USDC
});

// Read the current policy
const policy = agent.getPolicy();

// Check today's tracked spend
const { date, amount } = agent.getDailySpend();
console.log(`Spent ${amount} base units on ${date}`);

Environment Variables

Variable Required Description
AGENT_SOLANA_KEY For Solana Solana private key (base58 encoded)
AGENT_EVM_KEY For EVM EVM private key (hex, 0x prefixed)

Testing

Use devnet/testnet chains during development:

const agent = await PincerPayAgent.create({
  chains: ["solana-devnet"],
  solanaPrivateKey: process.env.AGENT_SOLANA_KEY!,
});

Getting Test USDC