Payment policies

Examples of configuring payment limits and restrictions.

Basic Policy Configuration

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { payments } from '@regent/x402';
import { createAgentApp } from '@regent/hono';

const agent = await createAgent({
  name: 'policy-agent',
  version: '1.0.0',
})
  .use(http())
  .use(payments({
    config: {
      payTo: '0x1234567890123456789012345678901234567890',
      facilitatorUrl: 'https://facilitator.example.com',
      network: 'base-sepolia',
      policyGroups: [
        {
          name: 'daily-limits',
          outgoingLimits: {
            global: {
              maxPaymentUsd: 10,      // Max $10 per payment
              maxTotalUsd: 100,       // Max $100 per day
              windowMs: 24 * 60 * 60 * 1000,
            },
          },
        },
      ],
    },
  }))
  .build();

const { app } = await createAgentApp(agent);

Outgoing Limits

Limit payments your agent makes to other agents:

const policyGroups = [
  {
    name: 'spending-limits',
    outgoingLimits: {
      // Global limit for all targets
      global: {
        maxPaymentUsd: 5,
        maxTotalUsd: 50,
        windowMs: 60 * 60 * 1000,  // 1 hour
      },
      // Per-target limits
      perTarget: {
        'https://expensive-agent.example.com': {
          maxPaymentUsd: 2,
          maxTotalUsd: 10,
        },
        'https://trusted-agent.example.com': {
          maxPaymentUsd: 20,
          maxTotalUsd: 200,
        },
      },
      // Per-endpoint limits
      perEndpoint: {
        'https://agent.example.com/entrypoints/premium/invoke': {
          maxPaymentUsd: 1,
        },
      },
    },
  },
];

Incoming Limits

Limit payments your agent accepts:

const policyGroups = [
  {
    name: 'income-limits',
    incomingLimits: {
      // Global incoming limit
      global: {
        maxTotalUsd: 1000,
        windowMs: 24 * 60 * 60 * 1000,
      },
      // Per-sender limits
      perSender: {
        '0xknown-whale-address': {
          maxTotalUsd: 500,
        },
      },
      // Per-endpoint limits
      perEndpoint: {
        '/entrypoints/bulk/invoke': {
          maxPaymentUsd: 100,
        },
      },
    },
  },
];

Recipient Whitelists/Blacklists

Control who your agent can pay:

const policyGroups = [
  {
    name: 'recipient-control',
    // Only allow payments to these recipients
    allowedRecipients: [
      'https://trusted-service.example.com',
      'https://partner-agent.example.com',
    ],
    // Block these recipients (takes precedence)
    blockedRecipients: [
      'https://blocked-agent.example.com',
      '*.malicious.com',
    ],
  },
];

Sender Whitelists/Blacklists

Control who can pay your agent:

const policyGroups = [
  {
    name: 'sender-control',
    // Only accept payments from these senders
    allowedSenders: [
      '0x1234567890123456789012345678901234567890',
      '*.trusted-domain.com',
    ],
    // Block these senders
    blockedSenders: [
      '0xbadactor1234567890123456789012345678901234',
      '*.spam-domain.com',
    ],
  },
];

Rate Limiting

Limit the number of payments in a time window:

const policyGroups = [
  {
    name: 'rate-limits',
    rateLimits: {
      maxPayments: 100,           // Max 100 payments
      windowMs: 60 * 60 * 1000,   // Per hour
    },
  },
];

Multiple Policy Groups

Combine multiple policies (all must pass):

const policyGroups = [
  {
    name: 'global-limits',
    outgoingLimits: {
      global: { maxPaymentUsd: 10, maxTotalUsd: 100 },
    },
    rateLimits: { maxPayments: 50, windowMs: 3600000 },
  },
  {
    name: 'trusted-partners',
    allowedRecipients: [
      'https://partner1.example.com',
      'https://partner2.example.com',
    ],
  },
  {
    name: 'security',
    blockedRecipients: ['*.malicious.com'],
    blockedSenders: ['*.spam.com'],
  },
];

Loading Policies from File

Create payment-policies.json:

[
  {
    "name": "production-limits",
    "outgoingLimits": {
      "global": {
        "maxPaymentUsd": 10.0,
        "maxTotalUsd": 1000.0,
        "windowMs": 86400000
      },
      "perTarget": {
        "https://expensive-service.com": {
          "maxTotalUsd": 100.0
        }
      }
    },
    "allowedRecipients": [
      "https://trusted-service.com"
    ],
    "rateLimits": {
      "maxPayments": 100,
      "windowMs": 3600000
    }
  }
]

Load in your agent:

import { policiesFromConfig } from '@regent/x402';

const policyGroups = policiesFromConfig('./payment-policies.json');

const agent = await createAgent({ name: 'my-agent', version: '1.0.0' })
  .use(http())
  .use(payments({
    config: {
      payTo: process.env.PAYMENTS_RECEIVABLE_ADDRESS!,
      facilitatorUrl: process.env.FACILITATOR_URL!,
      network: 'base-sepolia',
      policyGroups,
    },
  }))
  .build();

Storage Configuration

Configure where payment tracking data is stored:

const config = {
  payTo: '0x...',
  facilitatorUrl: 'https://...',
  network: 'base-sepolia',
  policyGroups: [...],
  storage: {
    // SQLite (default)
    type: 'sqlite',
    sqlite: { dbPath: '.data/payments.db' },

    // Or PostgreSQL
    // type: 'postgres',
    // postgres: { connectionString: process.env.DATABASE_URL },

    // Or in-memory (for testing)
    // type: 'in-memory',
  },
};

Complete Example

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { payments, paymentsFromEnv, policiesFromConfig } from '@regent/x402';
import { createAgentApp } from '@regent/hono';
import { z } from 'zod';

// Load policies from file
const policyGroups = policiesFromConfig('./payment-policies.json') || [
  {
    name: 'default',
    outgoingLimits: {
      global: { maxPaymentUsd: 10, maxTotalUsd: 100 },
    },
    rateLimits: { maxPayments: 50, windowMs: 3600000 },
  },
];

const agent = await createAgent({
  name: 'secure-agent',
  version: '1.0.0',
})
  .use(http())
  .use(payments({
    config: {
      ...paymentsFromEnv(),
      policyGroups,
      storage: { type: 'sqlite', sqlite: { dbPath: '.data/payments.db' } },
    },
  }))
  .addEntrypoint({
    key: 'premium',
    price: '0.50',
    input: z.object({ query: z.string() }),
    handler: async ({ input }) => ({
      output: { result: `Processed: ${input.query}` },
    }),
  })
  .build();

const { app } = await createAgentApp(agent);

Bun.serve({
  fetch: app.fetch,
  port: 3000,
});

console.log('Secure agent running on port 3000');