Payments

Manual payments and x402 protocol details.

Manual Payments

Use pay() to execute a payment directly without making a fetch request.

const result = await agent.pay(
  0.50,                              // Amount in USDC
  'https://api.example.com',         // Merchant identifier
  'So1ana...Address',                // Recipient Solana address
  { requestId: '123' }               // Optional metadata
);

console.log(result.signature); // Blockchain transaction signature
console.log(result.status);    // 'completed' or 'failed'

Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount in USDC
merchant	string	Yes	Merchant URL or identifier
merchantAddress	string	Yes	Recipient Solana address
metadata	object	No	Additional metadata

x402 Protocol

The x402 protocol enables HTTP-native payments. When a server requires payment, it returns:

HTTP/1.1 402 Payment Required
X-Payment-Required: true
Content-Type: application/json

{
  "amount": "0.50",
  "currency": "USDC",
  "address": "So1ana...Address",
  "network": "solana"
}

The AgentFish SDK automatically:

1. Detects the 402 response
2. Parses payment requirements
3. Executes the payment
4. Retries the original request with payment proof

Checking Payment Requirements

You can manually check if a response requires payment:

import { isPaymentRequired, parseX402Response } from '@agentfish/sdk';

const response = await fetch('https://api.example.com/data');

if (isPaymentRequired(response)) {
  const requirements = parseX402Response(response);
  console.log(`Payment required: $${requirements.amount} USDC`);
  console.log(`Send to: ${requirements.address}`);
}

Spending Limits

AgentFish enforces spending limits to protect your wallet:

• Per-transaction limit: Maximum amount for a single payment
• Daily limit: Maximum total spending per day

If a payment exceeds these limits, a PaymentLimitError is thrown.

try {
  await agent.fetch('https://expensive-api.com/data');
} catch (error) {
  if (error instanceof PaymentLimitError) {
    console.log(`Payment of $${error.requested} exceeds limit of $${error.limit}`);
  }
}

Payment Metadata

Attach metadata to payments for tracking and analytics:

const response = await agent.fetch('https://api.example.com/data', {
  metadata: {
    userId: 'user-123',
    requestType: 'chat',
    model: 'gpt-4',
  },
});

Metadata is stored with the payment and visible in your dashboard.