@piprail/sdk 1.3.0 → 1.4.0

package/CHAINS.md

@@ -6,7 +6,8 @@ themselves differ, and a few have **setup steps you must do before a wallet can
 receive**. This page is the exact list.
 
 **Most chains need nothing special.** The ones with caveats are **NEAR**, **TON**,
-**Stellar**, **XRPL**, and **Tron** — read those sections before you ship them.
+**Stellar**, **XRPL**, **Tron**, and **Algorand** (USDC needs a one-time ASA opt-in) —
+read those sections before you ship them.
 
 ## At a glance
 
@@ -15,6 +16,8 @@ receive**. This page is the exact list.
 | **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all) · USDT (all **except Base, World Chain, Sei**) | No | `{ privateKey }` |
 | **Solana** | ✅ SOL | USDC · USDT | No (payer creates the recipient's token account) | `{ secretKey }` |
 | **Sui** | ✅ SUI | USDC (no USDT) | No | `{ privateKey }` (`suiprivkey1…`) |
+| **Aptos** | ✅ APT | USDC · USDT | No (primary FA store auto-creates) | `{ privateKey }` (`ed25519-priv-0x…`) |
+| **Algorand** | ✅ ALGO | **USDC only** (Tether deprecated USDT) | USDC: ⚠️ **ASA opt-in** · **native ALGO: none** | `{ mnemonic }` (25 words) |
 | **Stellar** | ✅ XLM | USDC · EURC | ⚠️ **Yes — trustline + funded account** | `{ secret }` (`S…`) |
 | **XRP Ledger** | ✅ XRP | USDC · RLUSD (no USDT) | ⚠️ **Yes — trustline + activated account** | `{ seed }` (`s…`) |
 | **TON** | ✅ TON | **USD₮ only** (no USDC) | No (payer's gas auto-deploys the jetton wallet) | `{ mnemonic }` (24 words) |
@@ -22,12 +25,14 @@ receive**. This page is the exact list.
 | **NEAR** | ✅ NEAR | USDC · USDT | tokens: ⚠️ `storage_deposit` · **native NEAR: none** | `{ accountId, privateKey }` |
 
 > **`token: 'native'`** (paying in the chain's own coin) is accepted on **every family** —
-> EVM, Solana, Sui, Stellar, XRPL, TON, NEAR, **and Tron** (native TRX, digest-bound). No
-> exceptions. On NEAR, native is the **zero-setup** path: no `storage_deposit`, and a transfer
-> even creates a fresh recipient (the NEP-141 token path still needs `storage_deposit`).
+> EVM, Solana, Sui, Aptos, Algorand, Stellar, XRPL, TON, NEAR, **and Tron** (native TRX,
+> digest-bound). No exceptions. On NEAR, native is the **zero-setup** path: no `storage_deposit`,
+> and a transfer even creates a fresh recipient (the NEP-141 token path still needs
+> `storage_deposit`).
 >
 > **Custom tokens** work everywhere with no allowlist: EVM `{ address, decimals }` ·
-> Solana `{ mint, decimals }` · Sui `{ coinType, decimals }` · TON `{ master, decimals }` ·
+> Solana `{ mint, decimals }` · Sui `{ coinType, decimals }` · Aptos `{ metadata, decimals }` ·
+> Algorand `{ assetId, decimals }` · TON `{ master, decimals }` ·
 > Tron `{ address, decimals }` · NEAR `{ contractId, decimals }` · Stellar
 > `{ issuer, code, decimals }` · XRPL `{ issuer, currencyHex, decimals }`.
 
@@ -93,6 +98,23 @@ receive**. This page is the exact list.
 - **Finality is slow-ish:** verification waits for the tx to solidify (~19 blocks, ~57s); until then it reads as `tx_not_found` and is retried.
 - **Wallet:** `{ privateKey }` (32-byte hex, same format as EVM); addresses are Base58 `T…`.
 
+### Algorand — USDC needs a one-time ASA opt-in (native ALGO doesn't)
+- **Pay in:** `'native'` (ALGO, the zero-setup path), `'USDC'`, or a custom ASA `{ assetId, decimals }`. **USDC only for the stablecoin** — Tether deprecated/froze USDT on Algorand (2025-09-01), so it's not built in (pass it as a custom ASA if you must).
+- **Receiving USDC needs an ASA opt-in.** Before an account can *receive* USDC (ASA `31566704`) — or any ASA — it must **opt into that asset** once: a 0-amount asset-transfer to itself, which raises its minimum balance by 0.1 ALGO (locked, recoverable). No opt-in → the payment fails and PipRail returns `RECIPIENT_NOT_READY`. **Native ALGO needs no opt-in.** The payer is implicitly opted-in if it already holds USDC. The one-time opt-in is plain `algosdk` (PipRail stays a payments SDK, not a wallet manager):
+  ```ts
+  import algosdk from 'algosdk'
+  const algod = new algosdk.Algodv2('', 'https://mainnet-api.algonode.cloud', '')
+  const sp = await algod.getTransactionParams().do()
+  const optIn = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
+    sender: account.addr, receiver: account.addr, amount: 0, assetIndex: 31566704, suggestedParams: sp,
+  })
+  await algod.sendRawTransaction(optIn.signTxn(account.sk)).do() // one-time, per account per ASA
+  ```
+- **Fast + cheap:** ~3s single-step finality, flat 0.001 ALGO min fee. The challenge nonce rides in the transaction's **note field** (Template A), so the proof is bound to its challenge; verify reads the merchant account's inbound transfers via the indexer.
+- **x402:** Algorand's `exact` scheme is part of the official x402 standard, but the incumbent on-chain path uses a hosted **facilitator** — PipRail is the **backendless, no-facilitator** option (payer broadcasts, merchant verifies locally).
+- **Wallet:** `{ mnemonic }` (a 25-word Algorand recovery phrase) or `{ account }` (an algosdk `{ addr, sk }`).
+- **Endpoints:** `rpcUrl` overrides the **algod** endpoint (submit/params); the verify-side **indexer** uses the public AlgoNode default (override needs are rare; the public indexer is production-grade for the inbound-transfer read).
+
 ### Stellar — the receiver needs a trustline + a funded account
 - **Pay in:** `'native'` (XLM), `'USDC'`, `'EURC'`, or a custom `{ issuer, code, decimals }`.
 - **Receiving an issued asset needs a one-time TRUSTLINE.** The merchant (`payTo`) must (1) **exist** on-chain (funded above the ~1 XLM base reserve) and (2) hold a **trustline** (`changeTrust`) for that exact `code+issuer` *before* it can receive. No trustline → the payment fails. Each trustline locks **+0.5 XLM** of reserve. The **payer** likewise needs its own trustline to hold/send the asset.
@@ -130,6 +152,7 @@ Fix the *recipient*, not the payer:
 | `op_no_destination` | Stellar | the `payTo` account doesn't exist | create it with ≥1 XLM (base reserve) |
 | `op_no_trust` | Stellar | recipient has no trustline for the asset | add the trustline (+0.5 XLM reserve) |
 | `… is not registered` | NEAR | recipient isn't `storage_deposit`-registered on the token | call `storage_deposit` once (~0.00125 NEAR) |
+| `must optin` / `asset … missing from <payTo>` | Algorand | recipient hasn't opted into the USDC ASA | opt the recipient into the ASA once (0-amount self-transfer, +0.1 ALGO min balance) |
 
 Everything else (EVM, Solana, Sui, Tron, native TON/NEAR) needs no recipient setup, so you'll
 only ever see `INSUFFICIENT_FUNDS` there if the payer is short. Full taxonomy: **[ERRORS.md](./ERRORS.md)**.
@@ -143,9 +166,10 @@ right asset to `payTo`), but binds the proof to your challenge differently:
 
 - **Memo-bound** (the challenge nonce is written on-chain): **NEAR tokens** (ft_transfer
   memo), **TON** (transfer comment), **Stellar** (`MEMO_HASH = sha256(nonce)`), **XRPL**
-  (Memo + a derived DestinationTag).
+  (Memo + a derived DestinationTag), **Algorand** (the transaction's note field — native ALGO
+  and USDC alike).
 - **Digest-bound** (no on-chain nonce; the proof is the tx id, made single-use by the gate
-  + a recency window): **EVM**, **Solana**, **Sui**, **Tron**, and **native NEAR**. For
+  + a recency window): **EVM**, **Solana**, **Sui**, **Aptos**, **Tron**, and **native NEAR**. For
   these, a persistent `isUsed`/`markUsed` store + a tight `maxTimeoutSeconds` are
   load-bearing in multi-instance deployments (the default used-set is single-process).
 

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.4.0] — 2026-06-04
+
+A new chain **family** — **Algorand** — the **10th driver family**, bringing the built-in count to
+**28 chains across 10 families (19 EVM)**. Algorand is genuinely part of the **official x402
+standard** (its `exact` scheme is merged into the canonical x402 repo and the `@x402/avm` package),
+and one of the loudest agentic-commerce chains of 2026 — but the incumbent x402 path there is
+**facilitator-mediated**, so PipRail is the **first facilitator-free, backendless, verify-locally
+x402 SDK on Algorand**. Fully backward-compatible; `algosdk` is a lazy-loaded optional peer, so
+pure-EVM (and other) installs never download it.
+
+### Added
+- **Algorand (`chain: 'algorand'`, CAIP-2 `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k`)** — native
+  Circle **USDC** (ASA `31566704`, 6 dp) + native **ALGO** (6 dp). The USDC ASA was verified live on
+  mainnet (algod `/v2/assets/31566704` → unit-name `USDC`, decimals 6, creator = Circle's `2UEQ…`
+  account, url `centre.io/usdc`) before shipping. **USDC-only:** Tether deprecated USDT on Algorand
+  (frozen 2025-09-01), so it's intentionally omitted — pass it as a custom `{ assetId, decimals }`.
+- **Template A (memo-bound, like Stellar/XRPL/NEAR):** every Algorand transaction carries an
+  arbitrary **note field (≤1KB)**, so the challenge nonce rides in it verbatim (no hashing needed —
+  a UUID dwarfs nothing of the 1KB cap). `verify()` re-derives the watched account from the
+  **trusted `accept.payTo`** (never the client ref), reads its recent inbound transfers via the
+  indexer, and matches `note === nonce` + recipient + asset + amount + recency — a proof is
+  cryptographically bound to its challenge. Native ALGO is a `pay` txn; USDC/ASAs are `axfer`; both
+  carry the note. Amounts are integer base units (like EVM). `algosdk` is an **optional peer
+  (`>=3 <4`)**, lazy-loaded on first use; the built EVM bundle stays free of any static `algosdk`
+  import (its own chunk).
+- **Receive prerequisite:** to receive a USDC/ASA, the recipient must **opt into the ASA** (a
+  one-time 0-amount self-transfer) — conceptually identical to an XRPL/Stellar trustline. A submit
+  failure for a not-opted-in recipient maps to the typed `RecipientNotReadyError`; native ALGO needs
+  no opt-in.
+
+**Live-proven on Algorand mainnet — both assets, 12/12.** Real 402 → pay → confirm → verify → 200
+round-trips, each with balance moved + replay rejected (`tx_already_used`) + all agent surfaces
+green: **native ALGO** 6/6 (tx `AXXJVYAP7BLK6C76AWCJ3XA5HTECIRSCNRQ2WLFRNSZ6CD5GH32Q`) and
+**USDC** 6/6 (tx `INWCUUBAMIBYOPPUOBWXEHZQAQL6KSV7DPEEVGKAI64Z46TRQKOA`, merchant +0.05 USDC).
+Also verified against the test contract (typecheck + 441 tests + build + the lazy-chunk invariant).
+Funding follow-up: file an Algorand **xGov retroactive** grant for the shipped open-source SDK
+(SDKs/libraries are a named eligible category).
+
+## [1.3.1] — 2026-06-04
+
+Aptos pay-path fix surfaced by the live mainnet test — no API change, fully compatible with 1.3.0.
+
+### Fixed
+- **Aptos: cap `maxGasAmount` (50k) on the Fungible-Asset transfer.** Aptos validates
+  `max_gas_amount × gas_unit_price` against the sender's balance *before* execution, so the SDK
+  default (200k units) made a tiny transfer demand ~0.5 APT held just to be admitted — a wallet
+  with a modest APT balance was rejected with `INSUFFICIENT_BALANCE_FOR_TRANSACTION_FEE` even
+  though the transfer itself uses a fraction of that. A `primary_fungible_store::transfer` (even
+  one that creates the recipient's primary store) stays well under 50k gas units, so the cap keeps
+  ample gas headroom while the upfront fee requirement stays small. Live-validated on Aptos mainnet.
+
 ## [1.3.0] — 2026-06-04
 
 A new chain **family** — **Aptos** — the **9th driver family** and the only Move L1 with BOTH

package/ERRORS.md

@@ -2,8 +2,8 @@
 
 This is the **single source of truth** for how `@piprail/sdk` reports errors. It is
 deliberately small and uniform: every module — the client, the server gate, the registry,
-and every chain driver (all nine families: EVM, Solana, TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos,
-and any future one) — follows it
+and every chain driver (all ten families: EVM, Solana, TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos,
+Algorand, and any future one) — follows it
 *exactly*, so a human developer, a merchant server, or an AI agent always gets a **typed,
 understandable** reason, never an opaque chain-library blob.
 

package/README.md

@@ -1,6 +1,6 @@
 # @piprail/sdk
 
-**Accept crypto payments from any HTTP request — on any EVM chain, Solana, TON, Tron, NEAR, Sui, Stellar, and the XRP Ledger — in a couple of lines.**
+**Accept crypto payments from any HTTP request — on any EVM chain, Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar, and the XRP Ledger — in a couple of lines.**
 
 No middleman. No database. No fee. No account. Payments settle **straight into your wallet**, verified locally against your own RPC. Drop one middleware in front of a route and it's paid-only; point an agent at a paid URL and it pays itself.
 
@@ -90,7 +90,7 @@ See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK w
 
 ### Accept several chains at once
 
-`requirePayment` (and `createPaymentGate`) take an **`accept: [...]`** array — one challenge that's payable on **any** of several chains/tokens, across **all nine families** (EVM, Solana, TON, Tron, Stellar, XRPL, NEAR, Sui, Aptos). The agent pays with whatever it holds:
+`requirePayment` (and `createPaymentGate`) take an **`accept: [...]`** array — one challenge that's payable on **any** of several chains/tokens, across **all ten families** (EVM, Solana, TON, Tron, Stellar, XRPL, NEAR, Sui, Aptos, Algorand). The agent pays with whatever it holds:
 
 ```ts
 requirePayment({
@@ -133,7 +133,7 @@ requirePayment({ chain: 'ton',      token: 'native', amount: '1',     payTo }) /
 requirePayment({ chain: 'xrpl',     token: 'native', amount: '1',     payTo }) // XRP
 ```
 
-**Native or stablecoin — your choice, on every chain.** Every gate accepts the chain's native coin (ETH, BNB, POL, AVAX, SOL, TON, XLM, XRP, SUI, NEAR, **TRX**, …) just as readily as a stablecoin — set `token: 'native'` and the SDK fills in the right decimals (18 on EVM, 9 on Solana/TON/Sui, 7 on Stellar, 6 on XRPL/Tron, 24 on NEAR). Verification, replay protection, and self-custody are identical to the stablecoin path — across **all nine families, no exceptions**. (On **NEAR**, native is the zero-setup path — no `storage_deposit` — while the NEP-141 token path needs registration; see the NEAR note. On **Tron**, USD₮ is the default since TRX is volatile gas, but native TRX works too.)
+**Native or stablecoin — your choice, on every chain.** Every gate accepts the chain's native coin (ETH, BNB, POL, AVAX, SOL, TON, XLM, XRP, SUI, NEAR, **TRX**, …) just as readily as a stablecoin — set `token: 'native'` and the SDK fills in the right decimals (18 on EVM, 9 on Solana/TON/Sui, 8 on Aptos, 7 on Stellar, 6 on XRPL/Tron/Algorand, 24 on NEAR). Verification, replay protection, and self-custody are identical to the stablecoin path — across **all ten families, no exceptions**. (On **NEAR**, native is the zero-setup path — no `storage_deposit` — while the NEP-141 token path needs registration; see the NEAR note. On **Tron**, USD₮ is the default since TRX is volatile gas, but native TRX works too.)
 
 `token` is **required** — every gate states exactly what it accepts, so there's never any doubt whether a route takes USDC, USDT, or the native coin. Name a built-in symbol (`'USDC'`, `'USDT'`), use `'native'` for the chain's own coin (ETH, BNB, SOL, TON, XLM, …), or pass a custom token by address. The symbol is all you write — the SDK fills in the contract + decimals.
 
@@ -168,6 +168,7 @@ Every token address below was verified on-chain (symbol + decimals) before shipp
 | `'near'` | NEAR | USDC, USDT |
 | `'sui'` | Sui | USDC |
 | `'aptos'` | Aptos | USDC, USDT |
+| `'algorand'` | Algorand | USDC |
 | `'stellar'` | Stellar | USDC, EURC |
 | `'xrpl'` | XRP Ledger | USDC, RLUSD |
 
@@ -179,6 +180,8 @@ Every token address below was verified on-chain (symbol + decimals) before shipp
 
 **Sui note:** **USDC only** — no native USDT on Sui (Wormhole-bridged only). Native SUI works with `token: 'native'`.
 
+**Algorand note:** **USDC only** — Tether deprecated USDT on Algorand (frozen 2025-09-01), so it's intentionally absent (pass it as a custom `{ assetId, decimals }`). Native ALGO works with `token: 'native'` (the zero-setup path). To **receive** USDC the recipient must **opt into the ASA** once (a 0-amount self-transfer — like a trustline); a not-opted-in recipient surfaces `RECIPIENT_NOT_READY`. The challenge nonce binds inside the transaction's note field (Template A). Algorand's `exact` scheme is part of the official x402 standard; the incumbent on-chain path there uses a hosted facilitator, so PipRail is the backendless, no-facilitator option.
+
 **Stellar / XRPL note:** to **receive** an issued asset (USDC/EURC on Stellar; USDC/RLUSD on XRPL) the recipient needs a one-time **trustline** for that asset, and the account must already exist / be activated (a small native reserve — **locked, not spent**). Native XLM/XRP need no trustline. The payer needs its own trustline too.
 
 ### Using TON? Grab one free API key (≈30 seconds)
@@ -475,9 +478,9 @@ Two layers, one contract. Worth knowing if you're extending the SDK or auditing
 
 - **The protocol layer is chain-agnostic.** `server.ts` (`requirePayment`/`createPaymentGate`), `client.ts` (`PipRailClient`), `x402.ts` (wire envelopes), `policy.ts`, `ledger.ts`, and `agent.ts` depend **only** on the `PaymentDriver` contract in `drivers/types.ts` — zero `viem`, zero `@solana/web3.js`, zero chain SDK. The chain is data the caller passes, not an allowlist the SDK ships.
 - **The `PaymentDriver` contract.** `resolve(chain)` → a bound `ResolvedNetwork` exposing `resolveToken` · `describeAsset` · `assertValidPayTo` · `bindWallet` · `send` · `confirm` · `estimateCost` · `verify`. That's the entire boundary every family implements and the protocol layer ever sees.
-- **Families mirror each other file-for-file.** Each lives in `drivers/<family>/` as `chains` · `wallet` · `pay` · `verify` · `index`, with family-suffixed functions (`payEvm`/`paySui`/…, `verifyEvm`/`verifyNear`/…). Eight today: `evm`, `solana`, `ton`, `stellar`, `xrpl`, `tron`, `near`, `sui`. Adding one = copy the five files, implement the contract, `registerDriver` — the protocol layer never changes.
-- **Routing + lazy auto-mount.** `registry.ts` maps a `chain` value to its family synchronously (`familyForChain`). EVM is always present (viem is a hard peer); every non-EVM family **loads itself on first use** via one dynamic `import()`, so a pure-EVM install never downloads `@solana`/`@ton`/`@stellar`/`xrpl`/`tronweb`/`near-api-js`/`@mysten/sui`. A build-time invariant asserts the main bundle has **zero** static imports of those libs — only per-family lazy chunks.
-- **Two verification templates.** *Template A (memo-bound)* — Stellar, XRPL, TON, NEAR — carries the challenge nonce inside the transfer (memo / tag / comment), so the proof is cryptographically bound to its challenge. *Template B (digest-bound)* — EVM, Solana, Tron, Sui — binds via a single-use proof set + recipient + amount + a tight recency window (use a persistent `isUsed`/`markUsed` store in production).
+- **Families mirror each other file-for-file.** Each lives in `drivers/<family>/` as `chains` · `wallet` · `pay` · `verify` · `index`, with family-suffixed functions (`payEvm`/`paySui`/…, `verifyEvm`/`verifyNear`/…). Ten today: `evm`, `solana`, `ton`, `stellar`, `xrpl`, `tron`, `near`, `sui`, `aptos`, `algorand`. Adding one = copy the five files, implement the contract, `registerDriver` — the protocol layer never changes.
+- **Routing + lazy auto-mount.** `registry.ts` maps a `chain` value to its family synchronously (`familyForChain`). EVM is always present (viem is a hard peer); every non-EVM family **loads itself on first use** via one dynamic `import()`, so a pure-EVM install never downloads `@solana`/`@ton`/`@stellar`/`xrpl`/`tronweb`/`near-api-js`/`@mysten/sui`/`@aptos-labs/ts-sdk`/`algosdk`. A build-time invariant asserts the main bundle has **zero** static imports of those libs — only per-family lazy chunks.
+- **Two verification templates.** *Template A (memo-bound)* — Stellar, XRPL, TON, NEAR, Algorand — carries the challenge nonce inside the transfer (memo / tag / comment / note), so the proof is cryptographically bound to its challenge. *Template B (digest-bound)* — EVM, Solana, Tron, Sui, Aptos — binds via a single-use proof set + recipient + amount + a tight recency window (use a persistent `isUsed`/`markUsed` store in production).
 - **Gas estimation.** Every driver's `estimateCost` extracts its own per-chain fee math, shaped into one uniform `CostEstimate` by the shared `nativeCost()` helper (`util/cost.ts`).
 - **The tests are the contract** (`test/`, Vitest), and two living standards govern any change: **[ERRORS.md](./ERRORS.md)** (how every module reports errors) and **STANDARDS.md** (how anything in the SDK is built + the verification gate). Runnable examples — including a local Anvil end-to-end — live in [`examples/`](../examples).
 
@@ -499,11 +502,12 @@ A failed payment is almost always one of two things, and PipRail tells them apar
 
 | Chain | The recipient must… | Sender also needs |
 |---|---|---|
-| **EVM · Solana · Sui · Tron** | nothing (just be a valid address; Solana's token account is auto-created by the SDK) | native gas |
+| **EVM · Solana · Sui · Aptos · Tron** | nothing (just be a valid address; Solana's token account is auto-created by the SDK; Aptos's primary FA store auto-creates) | native gas |
 | **TON** | nothing for native; a jetton wallet auto-deploys on first receipt (sender pays the gas) | TON for gas |
 | **NEAR** | nothing for native; for a token, be `storage_deposit`-registered on it (NEP-145, ~0.00125 NEAR, one-time) | NEAR for gas |
 | **Stellar** | exist (created with ≥1 XLM base reserve); for USDC/EURC, hold a **trustline** (+0.5 XLM each) | base + trustline reserves |
 | **XRP Ledger** | be **activated** — hold ≥1 XRP base reserve to exist; for USDC/RLUSD, a **trustline** | keep its own 1 XRP reserve |
+| **Algorand** | nothing for native ALGO; for USDC, **opt into the ASA** once (a 0-amount self-transfer, ~0.1 ALGO min-balance bump) | ALGO for fees + its own opt-in |
 
 > These are anti-spam "state rent" rules built into each ledger — e.g. an XRPL account can't receive a sub-1-XRP first payment because that payment must create the account at its ≥1 XRP base reserve. PipRail surfaces them as `RECIPIENT_NOT_READY` with the fix, so a payment that "can't go through" is self-explanatory. Per-chain specifics live in **[CHAINS.md](./CHAINS.md)**.
 
@@ -526,7 +530,7 @@ The full standard every module follows is **[ERRORS.md](./ERRORS.md)**.
 |---|---|---|
 | `chain` | — | `'base'` / `'bnb'` / `'solana'` / `'ton'` / …, a viem `Chain`, or `{ id, rpcUrl }` (single-chain form) |
 | `amount` | — | Human-readable, e.g. `'0.05'` (single-chain form) |
-| `token` | — | `'USDC'` / `'USDT'`, `'native'`, or a custom `{ address, decimals }` (EVM/Tron) / `{ mint, decimals }` (Solana) / `{ master, decimals }` (TON) / `{ issuer, code, decimals }` (Stellar) / `{ issuer, currencyHex, decimals }` (XRPL) / `{ contractId, decimals }` (NEAR) / `{ coinType, decimals }` (Sui) — required for the single form |
+| `token` | — | `'USDC'` / `'USDT'`, `'native'`, or a custom `{ address, decimals }` (EVM/Tron) / `{ mint, decimals }` (Solana) / `{ master, decimals }` (TON) / `{ issuer, code, decimals }` (Stellar) / `{ issuer, currencyHex, decimals }` (XRPL) / `{ contractId, decimals }` (NEAR) / `{ coinType, decimals }` (Sui) / `{ metadata, decimals }` (Aptos) / `{ assetId, decimals }` (Algorand) — required for the single form |
 | `accept` | — | Multi-chain form: `[{ chain, token, amount, payTo?, rpcUrl? }, …]` — offer several chains in one challenge |
 | `payTo` | — | Wallet that receives the payment (per-option fallback in the multi form) |
 | `description` | — | Optional text shown to the agent in the challenge (what the payment is for) |
@@ -566,6 +570,8 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
 | Tron | `{ privateKey }` (32-byte hex — secp256k1) |
 | NEAR | `{ accountId, privateKey }` (privateKey = ed25519:… secret) |
 | Sui | `{ privateKey }` (suiprivkey1… bech32) or `{ keypair }` |
+| Aptos | `{ privateKey }` (ed25519-priv-0x… AIP-80) or `{ account }` |
+| Algorand | `{ mnemonic }` (25 words) or `{ account }` (algosdk `{ addr, sk }`) |
 
 **Hand an LLM a wallet:** `paymentTools(client)` → framework-agnostic tool descriptors (MCP / AI SDK / function-calling), budget enforced by the client.
 
@@ -576,7 +582,7 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
 ## Requirements
 
 - Node 20+ or a modern browser.
-- `viem ^2.21` (peer dep). Solana: `@solana/web3.js`, `@solana/spl-token`, `bs58` (optional peers). TON: `@ton/ton`, `@ton/core`, `@ton/crypto` (optional peers). Stellar: `@stellar/stellar-sdk` (optional peer). XRPL: `xrpl` (optional peer). Tron: `tronweb` (optional peer). NEAR: `near-api-js` (optional peer). Sui: `@mysten/sui` (optional peer).
+- `viem ^2.21` (peer dep). Solana: `@solana/web3.js`, `@solana/spl-token`, `bs58` (optional peers). TON: `@ton/ton`, `@ton/core`, `@ton/crypto` (optional peers). Stellar: `@stellar/stellar-sdk` (optional peer). XRPL: `xrpl` (optional peer). Tron: `tronweb` (optional peer). NEAR: `near-api-js` (optional peer). Sui: `@mysten/sui` (optional peer). Aptos: `@aptos-labs/ts-sdk` (optional peer). Algorand: `algosdk` (optional peer).
 
 ## License & trademark
 

package/dist/algorand-IDFUG5CI.cjs

@@ -0,0 +1,363 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+
+
+
+
+
+
+
+var _chunkIQGT65WScjs = require('./chunk-IQGT65WS.cjs');
+
+// src/drivers/algorand/index.ts
+var _algosdk = require('algosdk'); var _algosdk2 = _interopRequireDefault(_algosdk);
+
+// src/drivers/algorand/chains.ts
+var ALGO_DECIMALS = 6;
+var ALGO_SYMBOL = "ALGO";
+var ALGORAND_MAINNET = {
+  caip2: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k",
+  defaultAlgod: "https://mainnet-api.algonode.cloud",
+  defaultIndexer: "https://mainnet-idx.algonode.cloud",
+  tokens: {
+    // Circle USDC — ASA id + 6 decimals verified live on mainnet algod
+    // (/v2/assets/31566704 → unit-name "USDC", decimals 6, creator = Circle) before shipping.
+    // USDC-only: Tether deprecated USDT on Algorand, so it's intentionally omitted.
+    USDC: { assetId: 31566704, decimals: 6, symbol: "USDC" }
+  }
+};
+function algorandAssetId(assetId) {
+  return String(assetId);
+}
+function parseAlgorandAssetId(asset) {
+  if (asset === "native") return null;
+  if (!/^\d+$/.test(asset)) return null;
+  const n = Number(asset);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+// src/drivers/algorand/pay.ts
+async function payAlgorand(params) {
+  const { client, sk, sender, accept } = params;
+  const note = new TextEncoder().encode(accept.extra.nonce);
+  const amount = BigInt(accept.amount);
+  const assetId = parseAlgorandAssetId(accept.asset);
+  try {
+    const { txn, txId } = await client.build({
+      sender,
+      receiver: accept.payTo,
+      amount,
+      note,
+      ...assetId === null ? {} : { assetId }
+    });
+    await client.signSend({ txn, sk });
+    return txId;
+  } catch (err) {
+    const mapped = mapAlgorandError(err, accept.payTo);
+    if (mapped) throw mapped;
+    throw _nullishCoalesce(_chunkIQGT65WScjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+  }
+}
+function mapAlgorandError(err, payTo) {
+  const m = err instanceof Error ? err.message : String(err);
+  if (/must optin/i.test(m) || /missing from/i.test(m) && m.includes(payTo)) {
+    return new (0, _chunkIQGT65WScjs.RecipientNotReadyError)(
+      `Algorand recipient ${payTo} hasn't opted into this asset \u2014 it must opt in (a 0-amount asset transfer to itself) before it can receive. (Algorand: ${firstLine(m)})`,
+      { cause: err }
+    );
+  }
+  if (/overspend|below min|min(imum)? balance|tried to spend|balance \d+ below|asset \d+ missing from|insufficient|underflow/i.test(
+    m
+  )) {
+    return new (0, _chunkIQGT65WScjs.InsufficientFundsError)(
+      `Algorand payment failed: the sender can't cover it \u2014 token balance, ALGO for fees, the 0.1-ALGO minimum balance, or a missing asset opt-in on the sender. (Algorand: ${firstLine(m)})`,
+      { cause: err }
+    );
+  }
+  return null;
+}
+function firstLine(message) {
+  return message.split("\n")[0].slice(0, 160);
+}
+
+// src/drivers/algorand/verify.ts
+async function verifyAlgorand(params) {
+  const { reader, accept } = params;
+  const nonce = accept.extra.nonce;
+  const required = BigInt(accept.amount);
+  const wantAssetId = parseAlgorandAssetId(accept.asset);
+  let txs;
+  try {
+    txs = await reader.transactionsForAccount(accept.payTo, 50);
+  } catch (e) {
+    return rpcFailed(nonce);
+  }
+  const tx = txs.find((t) => typeof t.note === "string" && t.note === nonce);
+  if (!tx) return notFound(nonce);
+  if (typeof tx.roundTime === "number") {
+    const ageSeconds = Math.floor(Date.now() / 1e3) - tx.roundTime;
+    if (Number.isFinite(ageSeconds) && ageSeconds > accept.maxTimeoutSeconds) {
+      return {
+        ok: false,
+        error: "payment_expired",
+        detail: `Payment is ${ageSeconds}s old; max allowed is ${accept.maxTimeoutSeconds}s.`
+      };
+    }
+  }
+  const isNative = wantAssetId === null;
+  const typeOk = isNative ? tx.txType === "pay" : tx.txType === "axfer";
+  const assetOk = isNative ? tx.assetId == null : tx.assetId === wantAssetId;
+  if (!typeOk || tx.receiver !== accept.payTo || !assetOk) {
+    return {
+      ok: false,
+      error: "transfer_not_found",
+      detail: `Algorand tx ${tx.id} carries our nonce but has no matching ${isNative ? "ALGO" : `ASA ${wantAssetId}`} transfer to ${accept.payTo}.`
+    };
+  }
+  let paid = 0n;
+  try {
+    paid = tx.amount ? BigInt(tx.amount) : 0n;
+  } catch (e2) {
+    paid = 0n;
+  }
+  if (paid < required) {
+    return { ok: false, error: "amount_too_low", detail: `Paid ${paid}, required ${required}.` };
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "onchain-proof",
+      success: true,
+      network: accept.network,
+      transaction: tx.id,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: _nullishCoalesce(tx.sender, () => ( "")),
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function notFound(nonce) {
+  return {
+    ok: false,
+    error: "transfer_not_found",
+    detail: `No matching Algorand payment found for nonce ${nonce} (not yet settled, or wrong recipient/amount/asset/note).`
+  };
+}
+function rpcFailed(nonce) {
+  return {
+    ok: false,
+    error: "tx_not_found",
+    detail: `Could not read the Algorand indexer for nonce ${nonce} (transient RPC failure) \u2014 retry.`
+  };
+}
+
+// src/drivers/algorand/wallet.ts
+
+function assertAlgorandWallet(wallet, network) {
+  if (typeof wallet !== "object" || wallet === null) {
+    throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+      `chain ${network} is Algorand; wallet must be { mnemonic } (25 words) or { account }.`
+    );
+  }
+  if ("privateKey" in wallet || "walletClient" in wallet) {
+    throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+      `chain ${network} is Algorand; an EVM/Aptos wallet can't be used \u2014 pass { mnemonic } (25 words) or { account }.`
+    );
+  }
+  if ("secretKey" in wallet || "signer" in wallet || "secret" in wallet || "keypair" in wallet || "keyPair" in wallet || "seed" in wallet || "accountId" in wallet) {
+    throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+      `chain ${network} is Algorand; that looks like another family's wallet \u2014 pass { mnemonic } (25 words) or { account }.`
+    );
+  }
+  if (!("mnemonic" in wallet) && !("account" in wallet)) {
+    throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+      `chain ${network} is Algorand; wallet must be { mnemonic } (25 words) or { account }.`
+    );
+  }
+  return wallet;
+}
+function resolveAlgorandWallet(config) {
+  if (config.account) {
+    return { addr: String(config.account.addr), sk: config.account.sk };
+  }
+  if (config.mnemonic != null) {
+    try {
+      const { addr, sk } = _algosdk2.default.mnemonicToSecretKey(config.mnemonic);
+      return { addr: addr.toString(), sk };
+    } catch (cause) {
+      throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+        "Algorand wallet { mnemonic } is not a valid 25-word Algorand mnemonic.",
+        { cause }
+      );
+    }
+  }
+  throw new (0, _chunkIQGT65WScjs.WrongFamilyError)("Algorand wallet needs { mnemonic } (25 words) or { account }.");
+}
+
+// src/drivers/algorand/index.ts
+var algorandDriver = {
+  family: "algorand",
+  resolve(opts) {
+    if (opts.chain !== "algorand") return null;
+    const algodUrl = _nullishCoalesce(opts.rpcUrl, () => ( ALGORAND_MAINNET.defaultAlgod));
+    return makeAlgorandNetwork(ALGORAND_MAINNET, algodUrl);
+  }
+};
+function makeAlgorandNetwork(preset, algodUrl) {
+  const algod = new _algosdk2.default.Algodv2("", algodUrl, "");
+  const indexer = new _algosdk2.default.Indexer("", preset.defaultIndexer, "");
+  const network = preset.caip2;
+  const reader = {
+    async transactionsForAccount(account, limit) {
+      const res = await indexer.lookupAccountTransactions(account).limit(limit).do();
+      return (_nullishCoalesce(res.transactions, () => ( []))).map((t) => adaptTxn(t)).filter((r) => r !== null);
+    }
+  };
+  const payClient = {
+    async build(transfer) {
+      const suggestedParams = await algod.getTransactionParams().do();
+      const common = {
+        sender: transfer.sender,
+        receiver: transfer.receiver,
+        amount: transfer.amount,
+        note: transfer.note,
+        suggestedParams
+      };
+      const txn = transfer.assetId === void 0 ? _algosdk2.default.makePaymentTxnWithSuggestedParamsFromObject(common) : _algosdk2.default.makeAssetTransferTxnWithSuggestedParamsFromObject({
+        ...common,
+        assetIndex: transfer.assetId
+      });
+      return { txn, txId: txn.txID() };
+    },
+    async signSend({ txn, sk }) {
+      const signed = txn.signTxn(sk);
+      await algod.sendRawTransaction(signed).do();
+    }
+  };
+  return {
+    family: "algorand",
+    network,
+    supports: (n) => n === network,
+    resolveToken(token) {
+      if (token === "native") {
+        return { asset: "native", decimals: ALGO_DECIMALS, symbol: ALGO_SYMBOL };
+      }
+      if (typeof token === "string") {
+        const info = preset.tokens[token.toUpperCase()];
+        if (!info) {
+          const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
+          throw new (0, _chunkIQGT65WScjs.UnknownTokenError)(
+            `token "${token}" isn't built in for Algorand (known: ${known}). Pass { assetId, decimals } for a custom ASA, or use 'native'.`
+          );
+        }
+        return { asset: algorandAssetId(info.assetId), decimals: info.decimals, symbol: info.symbol };
+      }
+      _chunkIQGT65WScjs.rejectForeignToken.call(void 0, token, "algorand", network);
+      const t = token;
+      if (typeof t.assetId !== "number" || typeof t.decimals !== "number") {
+        throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+          `chain ${network} is Algorand; a custom token must be { assetId, decimals }.`
+        );
+      }
+      return {
+        asset: algorandAssetId(t.assetId),
+        decimals: t.decimals,
+        ...t.symbol ? { symbol: t.symbol } : {}
+      };
+    },
+    describeAsset(asset) {
+      if (asset === "native") return { symbol: ALGO_SYMBOL, decimals: ALGO_DECIMALS };
+      for (const info of Object.values(preset.tokens)) {
+        if (algorandAssetId(info.assetId) === asset) {
+          return { symbol: info.symbol, decimals: info.decimals };
+        }
+      }
+      return null;
+    },
+    assertValidPayTo(payTo) {
+      if (payTo.startsWith("0x")) {
+        throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+          `chain ${network} is Algorand, but payTo "${payTo}" looks like an EVM address.`
+        );
+      }
+      if (!_algosdk2.default.isValidAddress(payTo)) {
+        throw new (0, _chunkIQGT65WScjs.WrongFamilyError)(
+          `chain ${network} is Algorand, but payTo "${payTo}" is not a valid Algorand address.`
+        );
+      }
+    },
+    bindWallet(wallet) {
+      return { _native: assertAlgorandWallet(wallet, network) };
+    },
+    async send(wallet, accept) {
+      const signer = resolveAlgorandWallet(wallet._native);
+      return payAlgorand({ client: payClient, sk: signer.sk, sender: signer.addr, accept });
+    },
+    async confirm(ref) {
+      try {
+        const info = await _algosdk2.default.waitForConfirmation(algod, ref, 10);
+        return { height: String(_nullishCoalesce(info.confirmedRound, () => ( 0))) };
+      } catch (err) {
+        throw new (0, _chunkIQGT65WScjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
+          cause: err
+        });
+      }
+    },
+    async estimateCost() {
+      return _chunkIQGT65WScjs.nativeCost.call(void 0, {
+        symbol: ALGO_SYMBOL,
+        decimals: ALGO_DECIMALS,
+        fee: 1000n,
+        basis: "heuristic",
+        detail: "min fee 1000 \xB5Algos (1 transaction)"
+      });
+    },
+    async verify(_ref, accept) {
+      return verifyAlgorand({ reader, accept });
+    }
+  };
+}
+function adaptTxn(raw) {
+  const t = raw;
+  if (!t || typeof t.id !== "string") return null;
+  const note = t.note && t.note.length ? decodeNote(t.note) : void 0;
+  const base = {
+    id: t.id,
+    txType: String(_nullishCoalesce(t.txType, () => ( ""))),
+    ...note !== void 0 ? { note } : {},
+    ...t.sender != null ? { sender: String(t.sender) } : {},
+    ...typeof t.roundTime === "number" ? { roundTime: t.roundTime } : {}
+  };
+  if (t.paymentTransaction) {
+    const pt = t.paymentTransaction;
+    return {
+      ...base,
+      txType: "pay",
+      ...pt.receiver != null ? { receiver: String(pt.receiver) } : {},
+      ...pt.amount != null ? { amount: String(pt.amount) } : {}
+    };
+  }
+  if (t.assetTransferTransaction) {
+    const att = t.assetTransferTransaction;
+    return {
+      ...base,
+      txType: "axfer",
+      ...att.receiver != null ? { receiver: String(att.receiver) } : {},
+      ...att.amount != null ? { amount: String(att.amount) } : {},
+      ...att.assetId != null ? { assetId: Number(att.assetId) } : {}
+    };
+  }
+  return base;
+}
+function decodeNote(bytes) {
+  try {
+    return new TextDecoder().decode(bytes);
+  } catch (e3) {
+    return void 0;
+  }
+}
+
+
+exports.algorandDriver = algorandDriver;