---
name: algorand-x402-typescript
description: Builds x402 HTTP-native payment applications on Algorand using TypeScript. Covers clients (fetch, axios), servers (Express, Hono), facilitators, paywalls, Next.js integration, and the @x402/core library. Use when implementing x402 payment flows in TypeScript, creating payment-gated APIs, building x402 facilitators or paywalls, or integrating @x402/* packages.
title: algorand-x402-typescript
canonical_url: https://skilld.dev/gh/algorandfoundation/algorand-agent-skills/algorand-x402-typescript
last_updated: 2026-09-27T13:22:43.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 21 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install algorandfoundation/algorand-agent-skills/algorand-x402-typescript`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/algorand-x402-typescript`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/algorandfoundation/algorand-agent-skills/algorand-x402-typescript) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/algorand-x402-typescript`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/algorand-x402-typescript --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/algorand-x402-typescript --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# x402 on Algorand - TypeScript

Build x402 HTTP-native payment applications on Algorand with TypeScript. Use the reference files below for detailed guidance on each component.

## TypeScript Quick Start

```bash
# Core + AVM mechanism + key/signer helpers from algokit-utils
npm install @x402/core @x402/avm @algorandfoundation/algokit-utils

# Server middleware (pick one)
npm install @x402/express    # Express.js
npm install @x402/hono       # Hono
npm install @x402/next       # Next.js

# HTTP clients (pick one)
npm install @x402/fetch      # Fetch API (re-exports x402Client, wrapFetchWithPayment)
npm install @x402/axios      # Axios   (re-exports x402Client, wrapAxiosWithPayment)

# Optional: only needed for custom/manual signers (e.g., browser wallet flows)
npm install algosdk
```

### Register AVM Scheme

Every component registers the AVM exact scheme unconditionally — no environment variable guards:

Every AVM scheme is the same class — `ExactAvmScheme` — exported from three subpaths (each implementing a different `SchemeNetwork*` interface).

```typescript
// Client (x402Client is also re-exported from @x402/fetch and @x402/axios)
import { x402Client } from "@x402/core/client";
import { ExactAvmScheme } from "@x402/avm/exact/client";
import { toClientAvmSigner, ALGORAND_TESTNET_CAIP2 } from "@x402/avm";

// secretKeyBase64 = base64 of the 64-byte algosdk secret key (seed||pubkey) — NOT a mnemonic
const avmSigner = toClientAvmSigner(secretKeyBase64);
const client = new x402Client()
  .register(ALGORAND_TESTNET_CAIP2, new ExactAvmScheme(avmSigner));
```

```typescript
// Server (x402ResourceServer is also re-exported from @x402/hono, @x402/express, @x402/next)
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactAvmScheme } from "@x402/avm/exact/server";
import { ALGORAND_TESTNET_CAIP2 } from "@x402/avm";

const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
const server = new x402ResourceServer(facilitatorClient)
  .register(ALGORAND_TESTNET_CAIP2, new ExactAvmScheme());
```

```typescript
// Facilitator
import { x402Facilitator } from "@x402/core/facilitator";
import { ExactAvmScheme } from "@x402/avm/exact/facilitator";
import { toFacilitatorAvmSigner, ALGORAND_TESTNET_CAIP2 } from "@x402/avm";

const avmSigner = toFacilitatorAvmSigner(secretKeyBase64);
const facilitator = new x402Facilitator()
  .register(ALGORAND_TESTNET_CAIP2, new ExactAvmScheme(avmSigner));
```

The `register` builder also accepts a glob pattern (e.g. `"algorand:*"`) when you want one scheme to handle all Algorand networks. Use the exported CAIP-2 constants (`ALGORAND_TESTNET_CAIP2`, `ALGORAND_MAINNET_CAIP2`) when targeting a single network.

### Network identifiers

Always use the `ALGORAND_TESTNET_CAIP2` / `ALGORAND_MAINNET_CAIP2` constants from `@x402/avm` — never hardcode the CAIP-2 string. The value changed in `@x402/avm` 2.20.0 to the 32-char CAIP-2 reference form (`algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe` for TestNet, `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k` for MainNet); earlier releases used the full base64 genesis hash. The Python `x402-avm` package (2.0.2) still uses the full genesis hash form, so a TypeScript client/server paired with a Python facilitator (or vice-versa) will not match on `network` until both sides use the same form. As a mitigation, register with the `"algorand:*"` glob on the client and server so either form is accepted.

### Project setup

Node examples assume ESM (`"type": "module"` in `package.json`). Recommended `tsconfig.json`: `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`, `"target": "ES2022"`, `"strict": true`, `"types": ["node"]`. `@x402/*` packages ship both ESM and CJS builds.

### TypeScript algosdk Encoding

TypeScript algosdk works with raw `Uint8Array` directly — no conversion needed. This matches the `@txnlab/use-wallet` ecosystem standard. Encoding/decoding to/from base64 happens only at protocol boundaries (PAYMENT-SIGNATURE header serialization).

## Reference Guide

Navigate to the appropriate reference based on your task. Each topic has three files:
- **`{name}.md`** — Step-by-step implementation guide
- **`{name}-reference.md`** — API details and type signatures
- **`{name}-examples.md`** — Complete, runnable code samples

### Explaining x402 for TypeScript

Understand @x402/* TypeScript package structure, signer interfaces (ClientAvmSigner, FacilitatorAvmSigner), registration patterns, builder patterns, constants, and utilities.

- [explain-algorand-x402-typescript.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/explain-algorand-x402-typescript.md) — Package ecosystem explanation
- [explain-algorand-x402-typescript-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/explain-algorand-x402-typescript-reference.md) — API reference for @x402/* packages
- [explain-algorand-x402-typescript-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/explain-algorand-x402-typescript-examples.md) — TypeScript pattern examples

### Building Clients

Build HTTP clients with @x402/fetch or @x402/axios that automatically handle 402 payments. Covers wrapFetchWithPayment, wrapAxiosWithPayment, ClientAvmSigner for browser wallets or Node.js private keys.

- [create-typescript-x402-client.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-client.md) — Client creation guide
- [create-typescript-x402-client-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-client-reference.md) — Fetch/Axios API reference
- [create-typescript-x402-client-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-client-examples.md) — Client code examples

### Building Servers

Build payment-protected servers with @x402/express or @x402/hono middleware. Covers route pricing, multi-network support (AVM+EVM+SVM), 402 responses, and dynamic pricing.

- [create-typescript-x402-server.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-server.md) — Server creation guide
- [create-typescript-x402-server-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-server-reference.md) — Express/Hono middleware API reference
- [create-typescript-x402-server-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-server-examples.md) — Server code examples

### Building Next.js Apps

Build fullstack Next.js apps with @x402/next payment protection using paymentProxy and withX402. Covers App Router integration, middleware-level protection, and per-endpoint control. Requires Next.js 16.2.6+ and the `@x402/paywall` peer dependency (`npm install @x402/next @x402/paywall`).

- [create-typescript-x402-nextjs.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-nextjs.md) — Next.js integration guide
- [create-typescript-x402-nextjs-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-nextjs-reference.md) — Next.js API reference
- [create-typescript-x402-nextjs-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-nextjs-examples.md) — Next.js code examples

### Building Facilitators and Bazaar Discovery

Build facilitator services that verify and settle Algorand payments on-chain with @x402/avm. Covers FacilitatorAvmSigner, Express.js facilitator servers, and Bazaar discovery extension for API cataloging (bazaarResourceServerExtension, withBazaar, declare_discovery_extension on servers).

- [create-typescript-x402-facilitator.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-facilitator.md) — Facilitator creation guide (includes Bazaar setup in Step 5)
- [create-typescript-x402-facilitator-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-facilitator-reference.md) — Facilitator + Bazaar API reference
- [create-typescript-x402-facilitator-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-facilitator-examples.md) — Facilitator + Bazaar code examples

### Building Paywalls

Build browser paywall UIs with server-side middleware and client-side wallet integration (Pera, Defly, Lute) using @x402/avm. Covers PaywallBuilder, avmPaywall, multi-network paywalls.

- [create-typescript-x402-paywall.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-paywall.md) — Paywall creation guide
- [create-typescript-x402-paywall-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-paywall-reference.md) — Paywall API reference
- [create-typescript-x402-paywall-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/create-typescript-x402-paywall-examples.md) — Paywall code examples

### Low-Level SDK Usage

Use @x402/core and @x402/avm packages directly for custom integrations. Covers payment policies, AVM signer interfaces, transaction groups, fee abstraction, and low-level primitives.

- [use-typescript-x402-core-avm.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/use-typescript-x402-core-avm.md) — Core SDK usage guide
- [use-typescript-x402-core-avm-reference.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/use-typescript-x402-core-avm-reference.md) — Core/AVM API reference
- [use-typescript-x402-core-avm-examples.md](https://skilld.dev/api/skills-raw/algorandfoundation/algorand-agent-skills/algorand-x402-typescript/references/use-typescript-x402-core-avm-examples.md) — Core SDK code examples

## TypeScript Package Quick Reference

| Package | Purpose |
| ------- | ------- |
| `@x402/core` | Core protocol types and client/server/facilitator implementations |
| `@x402/avm` | Algorand Virtual Machine implementation with signers and transaction builders |
| `@x402/fetch` | HTTP Fetch wrapper with automatic 402 payment handling |
| `@x402/axios` | Axios wrapper with automatic 402 payment handling |
| `@x402/express` | Express.js payment middleware |
| `@x402/hono` | Hono payment middleware |
| `@x402/next` | Next.js payment middleware and route wrappers |
| `@x402/paywall` | Browser paywall UI builder for HTML 402 responses |
| `@x402/extensions` | Optional protocol extensions (e.g. Bazaar discovery, offer/receipt) |
| `@algorandfoundation/algokit-utils` | Algod client and transaction signing used internally by `toClientAvmSigner` / `toFacilitatorAvmSigner` (installed transitively by `@x402/avm`) |
| `algosdk` | Only required for custom/manual signer construction (browser wallets, advanced flows) |

## How to Use This Skill

1. **Start here** to understand which reference you need
2. **Read the `{name}.md`** file for step-by-step implementation guidance
3. **Consult `{name}-reference.md`** for API details
4. **Use `{name}-examples.md`** for complete, runnable code samples
