@halo/pay

@halo/pay is the HALO payment SDK for AI agents. It wraps HALO's agent-auth APIs, uses native fetch, and includes a transparent x402 payment helper.

Quick start

import { HaloClient } from "@halo/pay";
const halo = new HaloClient({ apiKey: process.env.HALO_API_KEY! });
await halo.pay({ amountMicroUsdc: "10000", recipientAddress: "0x1234567890123456789012345678901234567890", chain: "base-sepolia" });

Installation

npm install @halo/pay

Authentication

Create an agent in the HALO dashboard, then copy its API key. @halo/pay expects an agent key in the halo_sk_test_* format.

import { HaloClient } from "@halo/pay";

const halo = new HaloClient({
  apiKey: process.env.HALO_API_KEY!,
});

API reference

getBalance(chain?)

Returns the current agent wallet balance as micro-USDC.

const balance = await halo.getBalance("base-sepolia");

pay({ amountMicroUsdc, recipientAddress, chain? })

Creates a HALO intent and starts a native USDC payment.

const payment = await halo.pay({
  amountMicroUsdc: "2500000",
  recipientAddress: "0x1234567890123456789012345678901234567890",
  chain: "base-sepolia",
});

getIntent(intentId)

Fetches the latest status for a payment intent.

const intent = await halo.getIntent(payment.intentId);

getAgent()

Returns the authenticated agent profile and wallet metadata.

const agent = await halo.getAgent();

haloFetch(url, options, haloClient)

Retries a 402 Payment Required request by paying it through HALO and replaying the original HTTP request with the payment proof headers attached.

import { HaloClient, haloFetch } from "@halo/pay";

const halo = new HaloClient({ apiKey: process.env.HALO_API_KEY! });
const response = await haloFetch("https://example.com/paid-resource", { method: "GET" }, halo);

x402 transparent payment handler

haloFetch() detects x402 payment requirements from response headers or body, pays the required amount through HALO, then retries the original request with X-PAYMENT and PAYMENT-SIGNATURE headers already populated.

Chain support

• Base
• Ethereum
• Solana

Pass the HALO chain id you want to use, such as base-sepolia, ethereum-sepolia, or solana-devnet.

Error handling

The SDK throws typed errors:

• HaloError for general request failures
• HaloAuthError for invalid credentials
• HaloRateLimitError when retries are exhausted
• HaloInsufficientFundsError when HALO reports insufficient funds

import { HaloError } from "@halo/pay";

try {
  await halo.pay({ amountMicroUsdc: "10000", recipientAddress: "0x123..." });
} catch (error) {
  if (error instanceof HaloError) {
    console.error(error.statusCode, error.message);
  }
}

TypeScript support

@halo/pay ships with bundled type declarations in dist/index.d.ts, so it works out of the box in TypeScript projects.