@piprail/sdk 1.8.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,22 @@ 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
@@ -492,6 +508,7 @@ 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

package/README.md

@@ -272,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 |
@@ -507,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) {

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;

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;

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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.8.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",