@piprail/sdk 1.7.0 → 1.9.0

package/CHAINS.md

@@ -13,7 +13,7 @@ read those sections before you ship them.
 
 | Chain(s) | Pay in native coin? | Built-in stablecoins | Receiver needs setup? | Wallet input |
 |---|:--:|---|---|---|
-| **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, HyperEVM, Monad, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all) · USDT (all **except Base, World Chain, Sei, HyperEVM, Monad**) | No | `{ privateKey }` |
+| **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, HyperEVM, Monad, Kaia, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all **except Kaia**) · USDT (all **except Base, World Chain, Sei, HyperEVM, Monad**) | 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…`) |
@@ -45,9 +45,11 @@ read those sections before you ship them.
 
 ### EVM — Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, …
 - **Pay in:** native coin (`'native'`), `'USDC'`, `'USDT'`, or a custom `{ address, decimals }`.
-- **USDT gap:** built in on every preset **except Base, World Chain, Sei, HyperEVM, and Monad** (USDC only there).
+- **USDT gap:** built in on every preset **except Base, World Chain, Sei, HyperEVM, and Monad** (USDC only there). **Kaia** is the inverse — **USD₮ only** (no Circle-native USDC on Kaia).
 - **Decimals:** on **BNB Chain**, Binance-Peg USDC/USDT are **18 decimals**, not 6 (the SDK handles it; don't hardcode 6).
-- **USDT branding:** on **Arbitrum, Polygon, and Unichain** the canonical Tether is the omnichain **USD₮0 / USDT0** (LayerZero), and on **Celo** it's native **USD₮** — all genuine, Tether-issued, 6-decimal USDT at the addresses shipped (verified live on-chain by symbol/decimals/supply). You still ask for it as `token: 'USDT'`; only the on-chain `symbol()` string differs from the plain `USDT` your wallet may show elsewhere.
+- **Stablecoin provenance — issuer-native vs bridged (every shipped address verified on-chain 2026-06-08, incl. bridge markers).** Every address is the correct, canonical, 1:1-redeemable dollar token on its chain; what varies is *who issues it*. You request it as `'USDC'` / `'USDT'` either way — provenance matters only if you specifically require issuer-native settlement.
+  - **USDC** is **Circle-native** on every preset **except** **BNB** (Binance-Peg, 18-dp), **Mantle** (OP canonical-bridge), and **Scroll** (Bridged-USDC-Standard) — the last two are backed 1:1 by Circle USDC on Ethereum but are **not** Circle-issued on that chain (absent from Circle's native-USDC list).
+  - **USDT** is **Tether-native** on **Ethereum, Avalanche, Celo, Kaia** (EVM) and **Solana, Tron, TON, NEAR, Aptos** (non-EVM). Everywhere else it's bridged: **USDT0** (LayerZero omnichain, on-chain `symbol()` = `USD₮0`) on **Arbitrum, Polygon, Unichain**; a **canonical-bridge** token (chain-minted, backed by Tether's Ethereum USDT — not Tether-issued) on **Optimism, zkSync, Sonic, Linea, Injective, Mantle, Scroll**; and **Binance-Peg** (18-dp) on **BNB**. The on-chain `symbol()` may read `USDT`, `USD₮`, `USDt`, or `USD₮0`; all resolve via `token: 'USDT'`.
 - **Receiver setup:** none — any `0x…` address receives ERC-20 or native immediately.
 - **Any other EVM chain:** pass a viem `Chain` or `{ id, rpcUrl }` + `token: { address, decimals }`.
 

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.9.0] — 2026-06-08
+
+### Added
+- **Kaia** (ex-Klaytn, chainId 8217) — EVM preset for South Korea's stablecoin-settlement chain
+  (born from Kakao + LINE). Pay **native KAIA** or **Tether-native USD₮**
+  (`0xd077A400968890Eacc75cdc901F0356c943e4fDb`, verified on-chain: symbol `USD₮`, name
+  "Tether USD", 6 dp, no bridge markers). Circle issues no native USDC on Kaia, so USDC is
+  intentionally omitted (pass it as a custom token if you need a bridged one). Brings the built-in
+  set to **29 chains across 10 families** (20 EVM mainnets).
+
+### Changed
+- **CHAINS.md — verified stablecoin provenance.** Now documents, per chain, whether the shipped
+  USDC/USDT is issuer-native, **USDT0** (LayerZero), a **canonical-bridge** token, or **Binance-Peg** —
+  every address re-verified on-chain. Documentation only; no code or behaviour change, all tokens
+  unchanged.
+
+## [1.8.0] — 2026-06-06
+
+### Added
+- **Agent tool annotations.** Each of the five `paymentTools(client)` descriptors now carries an
+  advisory `annotations` object (MCP-style `ToolAnnotations`: `title`, `readOnlyHint`,
+  `destructiveHint`, `idempotentHint`, `openWorldHint`), so an MCP client or agent can reason about a
+  tool's nature and render the right consent. The three reads (`piprail_discover` / `quote` / `plan`)
+  are flagged **read-only**; `piprail_pay_request` is flagged **value-moving** (not read-only,
+  destructive, non-idempotent) so a client can surface that it's the one tool that spends;
+  `piprail_register` writes a listing but is non-destructive. New exported type `ToolAnnotations`.
+  Backward-compatible — `annotations` is optional and non-MCP runtimes ignore it. (`@piprail/mcp`
+  ≥ 0.2.2 passes them through on the wire.)
+
 ## [1.7.0] — 2026-06-06
 
 ### Added
@@ -479,6 +508,8 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.9.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.8.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.7.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.6.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.5.1]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -113,9 +113,15 @@ For **every rail the 402 offers on your chain**, the plan reads **token balance
 
 ```ts
 import { paymentTools } from '@piprail/sdk'
-const tools = paymentTools(client) // → [piprail_quote_payment, piprail_plan_payment, piprail_pay_request]
+const tools = paymentTools(client) // → [piprail_discover, piprail_quote_payment, piprail_plan_payment, piprail_pay_request, piprail_register]
 ```
 
+Each descriptor also carries advisory **`annotations`** (MCP-style `ToolAnnotations` — `title`,
+`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the three reads are flagged
+**read-only**, `piprail_pay_request` is flagged **value-moving** (the one tool that spends), and
+`piprail_register` is non-destructive — so an MCP client can render the right consent. They're hints,
+not the boundary; the spend policy is. `@piprail/mcp` advertises them on the wire.
+
 See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK wiring.
 
 ## Be discoverable — find and be found ($0, no backend)
@@ -162,6 +168,11 @@ const hits = await client.discover({ query: 'weather', maxPrice: 0.01 })
 const res = await client.fetch(hits[0].resource) // then quote → plan → pay as usual
 ```
 
+`network` defaults to `'self'` (your chain only); pass `'any'` to search every chain, or a CAIP-2 id
+(`'eip155:8453'`) for a specific one. Chain slugs map to CAIP-2 through the `SLUG_TO_CAIP2` table —
+adding a chain adds one entry there (see [DISCOVERY.md](./DISCOVERY.md) §2.5), and an unresolved
+network is kept, never hidden.
+
 **3) Emit a discovery file** — turn your gate's config into the artifacts a crawler reads (pure, no
 I/O); serve the result as a static file on **your own** origin:
 
@@ -173,11 +184,13 @@ const openapi = buildOpenApi({
   origin: 'https://api.example.com',
   resources: [await gate.describe('https://api.example.com/report')],
 })
-// serve `openapi` at https://api.example.com/openapi.json  (the OpenAPI-first convention indexes parse)
+// serve `openapi` at https://api.example.com/openapi.json — each priced op carries an `x-payment-info`
+// block (the field indexes crawl) plus a default root `x-generator` attribution stamp.
 // buildWellKnownX402(...) emits the legacy /.well-known/x402 file; buildX402DnsTxt(...) the _x402 DNS line
 ```
 
-For an LLM/MCP this is two tools: **`piprail_discover`** (find) and **`piprail_register`** (be found).
+For an LLM/MCP these are two more tools — **`piprail_discover`** (find) and **`piprail_register`**
+(be found) — on top of the three payment tools, so `paymentTools(client)` / `@piprail/mcp` expose **five**.
 
 > **Two honest caveats.** The open indexes assume the mainstream `exact` scheme, so to be *usefully*
 > listed also offer a standard `exact` USDC rail on Base/Solana (`discover()` results are
@@ -259,6 +272,7 @@ Every token address below was verified on-chain (symbol + decimals) before shipp
 | `'injective'` | Injective | USDC, USDT |
 | `'hyperevm'` | HyperEVM (Hyperliquid) | USDC |
 | `'monad'` | Monad | USDC |
+| `'kaia'` | Kaia (ex-Klaytn) | USDT |
 | `'solana'` | Solana | USDC, USDT |
 | `'ton'` | TON | USDT |
 | `'tron'` | Tron | USDT |
@@ -494,6 +508,8 @@ Agent                                  Your server
 
 Verification is local and confirms the transaction **succeeded, is recent, and actually moved the required amount of the right token to `payTo`** — then your handler runs and returns the data. The same proof can't be redeemed twice. **Self-custody throughout:** the payer signs and broadcasts their own transfer straight to your wallet; PipRail never holds funds and never takes a cut of a payment.
 
+It's a **pull** model: the caller hands you the exact tx ref in the `payment-signature` header, so `verify()` does a **targeted lookup on your own RPC** and answers **synchronously, in the same request** — no chain listener, no indexer, no accounts DB, no async notify. Why that matters vs. "just send a raw transfer" — with runnable proof and an honest scorecard — is laid out in [`examples/why-402/`](../examples/why-402/) (and the [root README](../README.md#-why-402-and-not-just-a-raw-transfer)).
+
 ## Receipts — record every payment
 
 Every verified payment produces an `X402Receipt` with exactly what you'd persist — the on-chain tx ref, who paid, the amount, and the token. The SDK stays **database-free**; it hands you the data and you store it however you like.

package/dist/index.cjs

@@ -85,6 +85,7 @@ var _viem = require('viem');
 
 
 
+
 
 
 var _chains = require('viem/chains');
@@ -236,6 +237,17 @@ var CHAINS = {
     tokens: {
       USDC: { address: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", decimals: 6, symbol: "USDC" }
     }
+  },
+  // Kaia (ex-Klaytn, chainId 8217) — Tether-native USD₮ verified on-chain 2026-06-08
+  // (0xd077…4fDb: symbol "USD₮", name "Tether USD", 6 dp, no bridge markers). Circle issues
+  // NO native USDC on Kaia (absent from Circle's list), so USDC is intentionally omitted —
+  // pay native KAIA or USD₮ (or pass a custom { address, decimals }). Asia's stablecoin-
+  // settlement chain, born from Kakao + LINE.
+  kaia: {
+    chain: _chains.kaia,
+    tokens: {
+      USDT: { address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb", decimals: 6, symbol: "USDT" }
+    }
   }
 };
 function isViemChain(input) {
@@ -2040,6 +2052,13 @@ function paymentTools(client) {
     {
       name: "piprail_discover",
       description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
+      annotations: {
+        title: "Discover payable x402 APIs",
+        readOnlyHint: true,
+        // reads the open indexes only; never pays
+        openWorldHint: true
+        // reaches external indexes (402 Index, CDP Bazaar)
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2076,6 +2095,13 @@ function paymentTools(client) {
     {
       name: "piprail_quote_payment",
       description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
+      annotations: {
+        title: "Quote an x402 price",
+        readOnlyHint: true,
+        // reads the 402 challenge; never pays
+        openWorldHint: true
+        // fetches an arbitrary URL
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2092,6 +2118,13 @@ function paymentTools(client) {
     {
       name: "piprail_plan_payment",
       description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      annotations: {
+        title: "Plan an x402 payment",
+        readOnlyHint: true,
+        // reads balances + the challenge; never pays
+        openWorldHint: true
+        // fetches a URL and reads chain state
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2130,6 +2163,17 @@ function paymentTools(client) {
     {
       name: "piprail_pay_request",
       description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      annotations: {
+        title: "Pay an x402 request",
+        readOnlyHint: false,
+        // this is the one tool that MOVES FUNDS
+        destructiveHint: true,
+        // an on-chain payment is value-moving and not reversible
+        idempotentHint: false,
+        // paying twice = two payments
+        openWorldHint: true
+        // fetches a URL and settles on-chain
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2180,6 +2224,16 @@ function paymentTools(client) {
     {
       name: "piprail_register",
       description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      annotations: {
+        title: "Register an x402 endpoint",
+        readOnlyHint: false,
+        // writes a listing to an external index
+        destructiveHint: false,
+        // adds a listing; nothing is destroyed and no funds move
+        openWorldHint: true
+        // posts to external indexes (402 Index)
+        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
+      },
       parameters: {
         type: "object",
         properties: {

package/dist/index.d.cts

@@ -838,7 +838,7 @@ declare const CHAINS: {
                         gasPrice: bigint;
                         maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas?: undefined | undefined;
-                        maxPriorityFeePerGas? /** Native coin metadata. Defaults to 18-decimal ETH. */: undefined | undefined;
+                        maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
                         sourceHash?: undefined | undefined;
@@ -3340,9 +3340,7 @@ declare const CHAINS: {
                         value: bigint;
                         yParity: number;
                         accessList: viem.AccessList;
-                        authorizationList
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
+                        authorizationList?: undefined | undefined;
                         blobVersionedHashes?: undefined | undefined;
                         chainId: number;
                         type: "eip2930";
@@ -3732,6 +3730,62 @@ declare const CHAINS: {
             };
         };
     };
+    kaia: {
+        chain: {
+            blockExplorers: {
+                readonly default: {
+                    readonly name: "KaiaScan";
+                    readonly url: "https://kaiascan.io";
+                    readonly apiUrl: "https://api-cypress.klaytnscope.com/api";
+                };
+            };
+            blockTime?: number | undefined | undefined;
+            contracts: {
+                readonly multicall3: {
+                    readonly address: "0xcA11bde05977b3631167028862bE2a173976CA11";
+                    readonly blockCreated: 96002415;
+                };
+            };
+            ensTlds?: readonly string[] | undefined;
+            id: 8217;
+            name: "Kaia";
+            nativeCurrency: {
+                readonly decimals: 18;
+                readonly name: "Kaia";
+                readonly symbol: "KAIA";
+            };
+            experimental_preconfirmationTime?: number | undefined | undefined;
+            rpcUrls: {
+                readonly default: {
+                    readonly http: readonly ["https://public-en.node.kaia.io"];
+                };
+            };
+            sourceId?: number | undefined | undefined;
+            testnet?: boolean | undefined | undefined;
+            custom?: Record<string, unknown> | undefined;
+            extendSchema?: Record<string, unknown> | undefined;
+            fees?: viem.ChainFees<undefined> | undefined;
+            formatters?: undefined;
+            prepareTransactionRequest?: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | [fn: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | undefined, options: {
+                runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+            }] | undefined;
+            serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
+            verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
+        };
+        tokens: {
+            USDT: {
+                address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb";
+                decimals: number;
+                symbol: string;
+            };
+        };
+    };
 };
 /** A built-in EVM chain name. */
 type ChainName = keyof typeof CHAINS;
@@ -4636,6 +4690,25 @@ declare class PipRailClient {
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
 
+/**
+ * MCP-style tool annotations — optional, advisory hints that let an MCP client or
+ * agent reason about a tool's *nature* (is it safe to call freely? does it move
+ * value?). They mirror the MCP spec's `ToolAnnotations`. NOTE: hints only — a
+ * client must never make a security decision solely on these; the spend policy is
+ * the real boundary.
+ */
+interface ToolAnnotations {
+    /** Human-friendly title for the tool. */
+    title?: string;
+    /** True when the tool only READS — no state change, no funds moved. */
+    readOnlyHint?: boolean;
+    /** True when the tool may move value or do something not easily undone (only meaningful when not read-only). */
+    destructiveHint?: boolean;
+    /** True when calling repeatedly with the same args has no additional effect. */
+    idempotentHint?: boolean;
+    /** True when the tool reaches the open world — external indexes, chains, or arbitrary URLs. */
+    openWorldHint?: boolean;
+}
 /** A framework-agnostic tool definition an agent runtime can register. */
 interface AgentTool {
     /** Unique tool name (snake_case, namespaced `piprail_…`). */
@@ -4644,6 +4717,8 @@ interface AgentTool {
     description: string;
     /** JSON Schema (draft-07 object) describing the arguments. */
     parameters: Record<string, unknown>;
+    /** Advisory MCP-style hints about the tool's nature (read-only, value-moving, …). */
+    annotations?: ToolAnnotations;
     /** Execute the tool. Returns a JSON-serialisable result. */
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
@@ -5296,4 +5371,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };

package/dist/index.d.ts

@@ -838,7 +838,7 @@ declare const CHAINS: {
                         gasPrice: bigint;
                         maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas?: undefined | undefined;
-                        maxPriorityFeePerGas? /** Native coin metadata. Defaults to 18-decimal ETH. */: undefined | undefined;
+                        maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
                         sourceHash?: undefined | undefined;
@@ -3340,9 +3340,7 @@ declare const CHAINS: {
                         value: bigint;
                         yParity: number;
                         accessList: viem.AccessList;
-                        authorizationList
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
+                        authorizationList?: undefined | undefined;
                         blobVersionedHashes?: undefined | undefined;
                         chainId: number;
                         type: "eip2930";
@@ -3732,6 +3730,62 @@ declare const CHAINS: {
             };
         };
     };
+    kaia: {
+        chain: {
+            blockExplorers: {
+                readonly default: {
+                    readonly name: "KaiaScan";
+                    readonly url: "https://kaiascan.io";
+                    readonly apiUrl: "https://api-cypress.klaytnscope.com/api";
+                };
+            };
+            blockTime?: number | undefined | undefined;
+            contracts: {
+                readonly multicall3: {
+                    readonly address: "0xcA11bde05977b3631167028862bE2a173976CA11";
+                    readonly blockCreated: 96002415;
+                };
+            };
+            ensTlds?: readonly string[] | undefined;
+            id: 8217;
+            name: "Kaia";
+            nativeCurrency: {
+                readonly decimals: 18;
+                readonly name: "Kaia";
+                readonly symbol: "KAIA";
+            };
+            experimental_preconfirmationTime?: number | undefined | undefined;
+            rpcUrls: {
+                readonly default: {
+                    readonly http: readonly ["https://public-en.node.kaia.io"];
+                };
+            };
+            sourceId?: number | undefined | undefined;
+            testnet?: boolean | undefined | undefined;
+            custom?: Record<string, unknown> | undefined;
+            extendSchema?: Record<string, unknown> | undefined;
+            fees?: viem.ChainFees<undefined> | undefined;
+            formatters?: undefined;
+            prepareTransactionRequest?: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | [fn: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | undefined, options: {
+                runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+            }] | undefined;
+            serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
+            verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
+        };
+        tokens: {
+            USDT: {
+                address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb";
+                decimals: number;
+                symbol: string;
+            };
+        };
+    };
 };
 /** A built-in EVM chain name. */
 type ChainName = keyof typeof CHAINS;
@@ -4636,6 +4690,25 @@ declare class PipRailClient {
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
 
+/**
+ * MCP-style tool annotations — optional, advisory hints that let an MCP client or
+ * agent reason about a tool's *nature* (is it safe to call freely? does it move
+ * value?). They mirror the MCP spec's `ToolAnnotations`. NOTE: hints only — a
+ * client must never make a security decision solely on these; the spend policy is
+ * the real boundary.
+ */
+interface ToolAnnotations {
+    /** Human-friendly title for the tool. */
+    title?: string;
+    /** True when the tool only READS — no state change, no funds moved. */
+    readOnlyHint?: boolean;
+    /** True when the tool may move value or do something not easily undone (only meaningful when not read-only). */
+    destructiveHint?: boolean;
+    /** True when calling repeatedly with the same args has no additional effect. */
+    idempotentHint?: boolean;
+    /** True when the tool reaches the open world — external indexes, chains, or arbitrary URLs. */
+    openWorldHint?: boolean;
+}
 /** A framework-agnostic tool definition an agent runtime can register. */
 interface AgentTool {
     /** Unique tool name (snake_case, namespaced `piprail_…`). */
@@ -4644,6 +4717,8 @@ interface AgentTool {
     description: string;
     /** JSON Schema (draft-07 object) describing the arguments. */
     parameters: Record<string, unknown>;
+    /** Advisory MCP-style hints about the tool's nature (read-only, value-moving, …). */
+    annotations?: ToolAnnotations;
     /** Execute the tool. Returns a JSON-serialisable result. */
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
@@ -5296,4 +5371,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };

package/dist/index.js

@@ -75,6 +75,7 @@ import {
   celo,
   hyperEvm,
   injective,
+  kaia,
   linea,
   mainnet,
   mantle,
@@ -236,6 +237,17 @@ var CHAINS = {
     tokens: {
       USDC: { address: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", decimals: 6, symbol: "USDC" }
     }
+  },
+  // Kaia (ex-Klaytn, chainId 8217) — Tether-native USD₮ verified on-chain 2026-06-08
+  // (0xd077…4fDb: symbol "USD₮", name "Tether USD", 6 dp, no bridge markers). Circle issues
+  // NO native USDC on Kaia (absent from Circle's list), so USDC is intentionally omitted —
+  // pay native KAIA or USD₮ (or pass a custom { address, decimals }). Asia's stablecoin-
+  // settlement chain, born from Kakao + LINE.
+  kaia: {
+    chain: kaia,
+    tokens: {
+      USDT: { address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb", decimals: 6, symbol: "USDT" }
+    }
   }
 };
 function isViemChain(input) {
@@ -2040,6 +2052,13 @@ function paymentTools(client) {
     {
       name: "piprail_discover",
       description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
+      annotations: {
+        title: "Discover payable x402 APIs",
+        readOnlyHint: true,
+        // reads the open indexes only; never pays
+        openWorldHint: true
+        // reaches external indexes (402 Index, CDP Bazaar)
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2076,6 +2095,13 @@ function paymentTools(client) {
     {
       name: "piprail_quote_payment",
       description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
+      annotations: {
+        title: "Quote an x402 price",
+        readOnlyHint: true,
+        // reads the 402 challenge; never pays
+        openWorldHint: true
+        // fetches an arbitrary URL
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2092,6 +2118,13 @@ function paymentTools(client) {
     {
       name: "piprail_plan_payment",
       description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      annotations: {
+        title: "Plan an x402 payment",
+        readOnlyHint: true,
+        // reads balances + the challenge; never pays
+        openWorldHint: true
+        // fetches a URL and reads chain state
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2130,6 +2163,17 @@ function paymentTools(client) {
     {
       name: "piprail_pay_request",
       description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      annotations: {
+        title: "Pay an x402 request",
+        readOnlyHint: false,
+        // this is the one tool that MOVES FUNDS
+        destructiveHint: true,
+        // an on-chain payment is value-moving and not reversible
+        idempotentHint: false,
+        // paying twice = two payments
+        openWorldHint: true
+        // fetches a URL and settles on-chain
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2180,6 +2224,16 @@ function paymentTools(client) {
     {
       name: "piprail_register",
       description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      annotations: {
+        title: "Register an x402 endpoint",
+        readOnlyHint: false,
+        // writes a listing to an external index
+        destructiveHint: false,
+        // adds a listing; nothing is destroyed and no funds move
+        openWorldHint: true
+        // posts to external indexes (402 Index)
+        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
+      },
       parameters: {
         type: "object",
         properties: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.7.0",
-  "description": "Accept x402 crypto payments across 28 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
+  "version": "1.9.0",
+  "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",