aixyz/accepts

Types and utilities for configuring x402 payment gating on agent and tool endpoints.

import type { Accepts, AcceptsX402, AcceptsX402Entry, AcceptsX402Multi, AcceptsFree } from "aixyz/accepts";
import { HTTPFacilitatorClient, facilitator, normalizeAcceptsX402, isAcceptsPaid } from "aixyz/accepts";

Types

`Accepts`

Union type for payment configuration. Supports a single payment option, free access, or an array of payment options for multi-network support:

type Accepts = AcceptsX402 | AcceptsFree | AcceptsX402Multi;

`AcceptsX402`

Requires x402 exact payment:

type AcceptsX402 = {
  scheme: "exact";
  price: string; // USD string, e.g. "$0.005"
  network?: string; // CAIP-2 chain ID, overrides config
  payTo?: string; // EVM address, overrides config
};

Field	Type	Required	Description
`scheme`	`string`	Yes	Must be `"exact"`
`price`	`string`	Yes	USD price string (e.g. `"$0.005"`)
`network`	`string`	No	CAIP-2 chain ID, overrides `x402.network` from config
`payTo`	`string`	No	EVM address to receive payment, overrides `x402.payTo` config

`AcceptsX402Entry`

A single payment option within a multi-accepts array. Same as AcceptsX402 but network is required — the server needs an explicit network to register each payment scheme:

type AcceptsX402Entry = {
  scheme: "exact";
  price: string;
  network: string; // required
  payTo?: string;
};

Field	Type	Required	Description
`scheme`	`string`	Yes	Must be `"exact"`
`price`	`string`	Yes	USD price string (e.g. `"$0.005"`)
`network`	`string`	Yes	CAIP-2 chain ID — required for multi-accepts
`payTo`	`string`	No	EVM address to receive payment, overrides `x402.payTo` config

`AcceptsX402Multi`

An array of payment entries, enabling multi-network support. Must contain at least one entry:

type AcceptsX402Multi = AcceptsX402Entry[];

`AcceptsFree`

No payment required:

type AcceptsFree = {
  scheme: "free";
};

Exports

`normalizeAcceptsX402`

Converts a single or multi accepts value into a uniform array:

function normalizeAcceptsX402(accepts: AcceptsX402 | AcceptsX402Multi): AcceptsX402[];

`isAcceptsPaid`

Type guard that returns true if the accepts config requires payment (i.e., is not { scheme: "free" }):

function isAcceptsPaid(accepts: Accepts): accepts is AcceptsX402 | AcceptsX402Multi;

`HTTPFacilitatorClient`

Client for communicating with an x402 facilitator service. Re-exported from @x402/core/server.

import { HTTPFacilitatorClient } from "aixyz/accepts";

const client = new HTTPFacilitatorClient({
  url: "https://x402.use-agently.com/facilitator",
});

`facilitator`

The default facilitator client used by AixyzApp. Points to the Agently-hosted x402 facilitator.

import { facilitator } from "aixyz/accepts";

`AcceptsScheme`

Zod schema for validating Accepts objects at runtime. Accepts a single object or an array of payment entries:

import { AcceptsScheme } from "aixyz/accepts";

// Single accepts
AcceptsScheme.parse({ scheme: "exact", price: "$0.005" });

// Multiple accepts
AcceptsScheme.parse([
  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
]);

Usage

Agents and tools declare an accepts export to control x402 payment gating. Endpoints without accepts are not registered.

app/agent.ts

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = {
  scheme: "exact",
  price: "$0.005",
};

app/tools/lookup.ts

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = {
  scheme: "free",
};

Multiple payment options

Accept payment across multiple networks by passing an array. Each entry requires an explicit network:

app/agent.ts

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = [
  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
];

All referenced networks are automatically registered with the payment gateway during initialization — no manual setup required.

Custom facilitator

Create app/accepts.ts to override the default facilitator:

app/accepts.ts

import { HTTPFacilitatorClient } from "aixyz/accepts";

export const facilitator = new HTTPFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL ?? "https://x402.use-agently.com/facilitator",
});

​Types

​Accepts

​AcceptsX402

​AcceptsX402Entry

​AcceptsX402Multi

​AcceptsFree

​Exports

​normalizeAcceptsX402

​isAcceptsPaid

​HTTPFacilitatorClient

​facilitator

​AcceptsScheme

​Usage

​Multiple payment options

​Custom facilitator