@piprail/sdk 1.5.0 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHAINS.md +2 -2
- package/CHANGELOG.md +29 -0
- package/ERRORS.md +4 -3
- package/README.md +7 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +22 -14
- package/dist/index.d.ts +22 -14
- package/dist/index.js +1 -1
- package/package.json +2 -2
package/CHAINS.md
CHANGED
|
@@ -13,7 +13,7 @@ read those sections before you ship them.
|
|
|
13
13
|
|
|
14
14
|
| Chain(s) | Pay in native coin? | Built-in stablecoins | Receiver needs setup? | Wallet input |
|
|
15
15
|
|---|:--:|---|---|---|
|
|
16
|
-
| **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 }` |
|
|
16
|
+
| **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 }` |
|
|
17
17
|
| **Solana** | ✅ SOL | USDC · USDT | No (payer creates the recipient's token account) | `{ secretKey }` |
|
|
18
18
|
| **Sui** | ✅ SUI | USDC (no USDT) | No | `{ privateKey }` (`suiprivkey1…`) |
|
|
19
19
|
| **Aptos** | ✅ APT | USDC · USDT | No (primary FA store auto-creates) | `{ privateKey }` (`ed25519-priv-0x…`) |
|
|
@@ -45,7 +45,7 @@ read those sections before you ship them.
|
|
|
45
45
|
|
|
46
46
|
### EVM — Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, …
|
|
47
47
|
- **Pay in:** native coin (`'native'`), `'USDC'`, `'USDT'`, or a custom `{ address, decimals }`.
|
|
48
|
-
- **USDT gap:** built in on every preset **except Base, World Chain, and
|
|
48
|
+
- **USDT gap:** built in on every preset **except Base, World Chain, Sei, HyperEVM, and Monad** (USDC only there).
|
|
49
49
|
- **Decimals:** on **BNB Chain**, Binance-Peg USDC/USDT are **18 decimals**, not 6 (the SDK handles it; don't hardcode 6).
|
|
50
50
|
- **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.
|
|
51
51
|
- **Receiver setup:** none — any `0x…` address receives ERC-20 or native immediately.
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,28 @@ All notable changes to `@piprail/sdk` are documented here. The format
|
|
|
4
4
|
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
|
|
5
5
|
versions follow [Semantic Versioning](https://semver.org/).
|
|
6
6
|
|
|
7
|
+
## [1.5.1] — 2026-06-04
|
|
8
|
+
|
|
9
|
+
**Cosmetic polish — docs & comments only, zero behavior change.** A repo-wide tidy pass so the
|
|
10
|
+
in-code docs match the SDK as it actually ships (10 families / 28 chains). No runtime, API, type,
|
|
11
|
+
or wire change — every existing program behaves identically.
|
|
12
|
+
|
|
13
|
+
- **JSDoc parity across the public surface.** The `chain` / `token` / `payTo` / wallet docs on
|
|
14
|
+
`RequirePaymentOptions`, `AcceptOption`, and `PipRailClientOptions` now enumerate all 10 families
|
|
15
|
+
(Aptos + Algorand were missing); the typed error JSDoc (`WrongFamilyError`, `UnknownTokenError`,
|
|
16
|
+
`MissingDriverError`, `RecipientNotReadyError`) lists every family + install command + custom-token form.
|
|
17
|
+
- **Stale comments corrected.** Native TRX and native NEAR are documented as the payment assets they've
|
|
18
|
+
been since 1.1.0 (the old "not a payment asset" / "`'native'` is rejected" notes were removed); the
|
|
19
|
+
`'native'` coin list, the barrel header, the tsup code-split note, and the lazy-mount docs now name all
|
|
20
|
+
9 non-EVM families; the `paymentTools` doc says "three tools" (quote · plan · pay).
|
|
21
|
+
- **Driver-family symmetry.** `evm/wallet.ts` gained the `── EVM SECTION: wallet ──` banner the other 9
|
|
22
|
+
families carry, and `evm/index.ts`'s `recipientReady()` comment now uses the shared "No receive
|
|
23
|
+
prerequisite —" lead-in.
|
|
24
|
+
- **Docs:** README contract-method list adds `balanceOf` / `recipientReady`; README custom-token examples
|
|
25
|
+
add Aptos + Algorand; CHAINS.md lists HyperEVM + Monad (and their USDT gap); ERRORS.md + AGENTS.md list
|
|
26
|
+
all 10 families; CHANGELOG version footer links restored.
|
|
27
|
+
- **Packaging:** `algosdk` moved to its alphabetical slot in `peerDependencies` (no dependency change).
|
|
28
|
+
|
|
7
29
|
## [1.5.0] — 2026-06-04
|
|
8
30
|
|
|
9
31
|
**The killer agent feature — `client.planPayment(url)`.** A read-only call that surveys a 402
|
|
@@ -384,6 +406,13 @@ straight into your wallet. The API is small and self-contained.
|
|
|
384
406
|
to your wallet; PipRail never holds funds.
|
|
385
407
|
- `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
|
|
386
408
|
|
|
409
|
+
[1.5.1]: https://www.npmjs.com/package/@piprail/sdk
|
|
410
|
+
[1.5.0]: https://www.npmjs.com/package/@piprail/sdk
|
|
411
|
+
[1.4.0]: https://www.npmjs.com/package/@piprail/sdk
|
|
412
|
+
[1.3.1]: https://www.npmjs.com/package/@piprail/sdk
|
|
413
|
+
[1.3.0]: https://www.npmjs.com/package/@piprail/sdk
|
|
414
|
+
[1.2.0]: https://www.npmjs.com/package/@piprail/sdk
|
|
415
|
+
[1.1.1]: https://www.npmjs.com/package/@piprail/sdk
|
|
387
416
|
[1.1.0]: https://www.npmjs.com/package/@piprail/sdk
|
|
388
417
|
[1.0.0]: https://www.npmjs.com/package/@piprail/sdk
|
|
389
418
|
[0.1.0]: https://www.npmjs.com/package/@piprail/sdk
|
package/ERRORS.md
CHANGED
|
@@ -205,9 +205,10 @@ the reader, full raw detail for the debugger — both, always. Chains with no re
|
|
|
205
205
|
|
|
206
206
|
## 7. Registry / loader pattern
|
|
207
207
|
|
|
208
|
-
- EVM is registered eagerly (`viem` is the one hard peer dep).
|
|
209
|
-
lazily via a single dynamic
|
|
210
|
-
first time
|
|
208
|
+
- EVM is registered eagerly (`viem` is the one hard peer dep). Every non-EVM family (Solana,
|
|
209
|
+
TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos, Algorand) mounts lazily via a single dynamic
|
|
210
|
+
`import()` in [`drivers/index.ts`](src/drivers/index.ts) the first time its `chain` is
|
|
211
|
+
named — no setup call.
|
|
211
212
|
- A failed lazy `import()` → `MissingDriverError` naming the exact `npm install` + `{ cause }`.
|
|
212
213
|
The in-flight promise isn't cached on failure, so a later call can retry.
|
|
213
214
|
- No driver for the family, or `resolve()` → `null` → `UnsupportedNetworkError`.
|
package/README.md
CHANGED
|
@@ -276,6 +276,12 @@ requirePayment({ chain: 'near', token: { contractId: 'token.near', decimals: 6 }
|
|
|
276
276
|
|
|
277
277
|
// On Sui, a custom coin is { coinType, decimals }:
|
|
278
278
|
requirePayment({ chain: 'sui', token: { coinType: '0x…::usdc::USDC', decimals: 6 }, amount: '0.05', payTo })
|
|
279
|
+
|
|
280
|
+
// On Aptos, a custom Fungible Asset is { metadata, decimals }:
|
|
281
|
+
requirePayment({ chain: 'aptos', token: { metadata: '0x…', decimals: 6 }, amount: '0.05', payTo })
|
|
282
|
+
|
|
283
|
+
// On Algorand, a custom ASA is { assetId, decimals }:
|
|
284
|
+
requirePayment({ chain: 'algorand', token: { assetId: 12345678, decimals: 6 }, amount: '0.05', payTo })
|
|
279
285
|
```
|
|
280
286
|
|
|
281
287
|
> **Production:** the built-in chains use public RPCs (rate-limited). Pass your own `rpcUrl` for real traffic.
|
|
@@ -603,7 +609,7 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
|
|
|
603
609
|
|
|
604
610
|
**Hand an LLM a wallet:** `paymentTools(client)` → framework-agnostic tool descriptors (MCP / AI SDK / function-calling), budget enforced by the client.
|
|
605
611
|
|
|
606
|
-
**Bring your own chain family:** the SDK is built on a tiny `PaymentDriver` contract — `resolve(chain)` returns a bound network with `resolveToken` / `describeAsset` / `assertValidPayTo` / `bindWallet` / `send` / `confirm` / `estimateCost` / `verify`. Register your own with `registerDriver(...)`; the protocol layer never changes (see [Architecture](#architecture-under-the-hood)).
|
|
612
|
+
**Bring your own chain family:** the SDK is built on a tiny `PaymentDriver` contract — `resolve(chain)` returns a bound network with `resolveToken` / `describeAsset` / `assertValidPayTo` / `bindWallet` / `send` / `confirm` / `estimateCost` / `balanceOf` / `recipientReady` / `verify`. Register your own with `registerDriver(...)`; the protocol layer never changes (see [Architecture](#architecture-under-the-hood)).
|
|
607
613
|
|
|
608
614
|
**Universal x402 (experimental):** building blocks to pay servers on the mainstream x402 `exact` scheme (EIP-3009 + facilitator) — `parseExactRequirements`, `buildExactAuthorization`, `encodeXPaymentHeader`. EVM-only; validate against your target facilitator before production.
|
|
609
615
|
|
package/dist/index.cjs
CHANGED
|
@@ -733,7 +733,7 @@ function makeEvmNetwork(resolved) {
|
|
|
733
733
|
}
|
|
734
734
|
return { token, native };
|
|
735
735
|
},
|
|
736
|
-
//
|
|
736
|
+
// No receive prerequisite — any 0x address receives native or ERC-20 immediately.
|
|
737
737
|
async recipientReady() {
|
|
738
738
|
return { ready: "n/a" };
|
|
739
739
|
},
|
package/dist/index.d.cts
CHANGED
|
@@ -3845,7 +3845,7 @@ interface AlgorandToken {
|
|
|
3845
3845
|
}
|
|
3846
3846
|
/**
|
|
3847
3847
|
* What to be paid in. Each driver validates the forms it accepts:
|
|
3848
|
-
* - 'native' the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
|
|
3848
|
+
* - 'native' the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP, TRX, NEAR, SUI, APT, ALGO)
|
|
3849
3849
|
* - 'USDC' (string) a symbol resolved against the chosen chain
|
|
3850
3850
|
* - EvmToken any ERC-20 (EVM chains)
|
|
3851
3851
|
* - SolanaToken any SPL token (Solana)
|
|
@@ -4130,6 +4130,8 @@ type PipRailEvent = {
|
|
|
4130
4130
|
* - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
|
|
4131
4131
|
* - XRPL → `{ seed }` (s… seed) or a ready `{ wallet }`
|
|
4132
4132
|
* - NEAR → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
|
|
4133
|
+
* - Aptos → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
|
|
4134
|
+
* - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
|
|
4133
4135
|
*/
|
|
4134
4136
|
type WalletInput = {
|
|
4135
4137
|
privateKey: string;
|
|
@@ -4263,7 +4265,7 @@ interface PipRailClientOptions {
|
|
|
4263
4265
|
/** Wallet for the chosen chain family. */
|
|
4264
4266
|
wallet: WalletInput;
|
|
4265
4267
|
/** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
|
|
4266
|
-
* 'xrpl', 'tron', 'sui', or '
|
|
4268
|
+
* 'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
|
|
4267
4269
|
chain: ChainSelector;
|
|
4268
4270
|
/** Override the chain's default RPC URL (recommended in production). */
|
|
4269
4271
|
rpcUrl?: string;
|
|
@@ -4441,8 +4443,10 @@ interface AgentTool {
|
|
|
4441
4443
|
invoke: (args: Record<string, unknown>) => Promise<unknown>;
|
|
4442
4444
|
}
|
|
4443
4445
|
/**
|
|
4444
|
-
*
|
|
4446
|
+
* Three tools wrapping a configured {@link PipRailClient}:
|
|
4445
4447
|
* - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
|
|
4448
|
+
* - `piprail_plan_payment(url)` — check you CAN pay (balance + gas + recipient
|
|
4449
|
+
* readiness) across every rail the URL offers, WITHOUT paying.
|
|
4446
4450
|
* - `piprail_pay_request(url, method?, body?)` — pay if needed and return the result.
|
|
4447
4451
|
*
|
|
4448
4452
|
* A policy/approval refusal comes back as a structured `{ declined: true, reason }`
|
|
@@ -4478,7 +4482,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
|
|
|
4478
4482
|
*/
|
|
4479
4483
|
interface AcceptOption {
|
|
4480
4484
|
/** Which chain. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar', 'xrpl',
|
|
4481
|
-
* 'tron', 'near', or '
|
|
4485
|
+
* 'tron', 'near', 'sui', 'aptos', or 'algorand'. */
|
|
4482
4486
|
chain: ChainSelector;
|
|
4483
4487
|
/** Token to be paid in (symbol / 'native' / custom descriptor). */
|
|
4484
4488
|
token: TokenInput;
|
|
@@ -4492,8 +4496,9 @@ interface AcceptOption {
|
|
|
4492
4496
|
interface RequirePaymentOptions {
|
|
4493
4497
|
/**
|
|
4494
4498
|
* Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
|
|
4495
|
-
* 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near',
|
|
4496
|
-
* `chain` + `token` + `amount`, OR use the multi-chain
|
|
4499
|
+
* 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', 'sui', 'aptos', or
|
|
4500
|
+
* 'algorand'. Provide `chain` + `token` + `amount`, OR use the multi-chain
|
|
4501
|
+
* `accept` array below.
|
|
4497
4502
|
*/
|
|
4498
4503
|
chain?: ChainSelector;
|
|
4499
4504
|
/** Override the chain's default RPC URL (recommended in production). */
|
|
@@ -4504,9 +4509,10 @@ interface RequirePaymentOptions {
|
|
|
4504
4509
|
* `{ address, decimals }` on EVM/Tron, `{ mint, decimals }` on Solana,
|
|
4505
4510
|
* `{ master, decimals }` on TON, `{ issuer, code, decimals }` on Stellar,
|
|
4506
4511
|
* `{ issuer, currencyHex, decimals }` on XRPL, `{ contractId, decimals }` on
|
|
4507
|
-
* NEAR, `{ coinType, decimals }` on Sui
|
|
4512
|
+
* NEAR, `{ coinType, decimals }` on Sui, `{ metadata, decimals }` on Aptos, or
|
|
4513
|
+
* `{ assetId, decimals }` on Algorand. You name the token; the SDK fills in
|
|
4508
4514
|
* the contract + decimals for built-in symbols. (Note: native USDC doesn't
|
|
4509
|
-
* exist on TON/Tron — USDT does; NEAR is
|
|
4515
|
+
* exist on TON/Tron — USDT does; native NEAR is supported via `'native'`.)
|
|
4510
4516
|
*/
|
|
4511
4517
|
token?: TokenInput;
|
|
4512
4518
|
/** Human-readable amount, e.g. "0.05" (single-chain form). */
|
|
@@ -4518,8 +4524,8 @@ interface RequirePaymentOptions {
|
|
|
4518
4524
|
*/
|
|
4519
4525
|
accept?: AcceptOption[];
|
|
4520
4526
|
/** Address that receives the payment (0x… EVM/Sui, base58 Solana, EQ…/UQ… TON,
|
|
4521
|
-
* G… Stellar, r… XRPL, T… Tron, account id on NEAR
|
|
4522
|
-
* form; the per-option fallback for the multi form. */
|
|
4527
|
+
* G… Stellar, r… XRPL, T… Tron, account id on NEAR, 0x… Aptos, base32 Algorand).
|
|
4528
|
+
* Required for the single form; the per-option fallback for the multi form. */
|
|
4523
4529
|
payTo?: AddressId;
|
|
4524
4530
|
/** Shown to the agent in the challenge. */
|
|
4525
4531
|
description?: string;
|
|
@@ -4669,7 +4675,7 @@ declare class InsufficientFundsError extends PipRailError {
|
|
|
4669
4675
|
* The message states the requirement and the fix in plain language **and echoes
|
|
4670
4676
|
* the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
|
|
4671
4677
|
* chain error is preserved on `.cause` for deeper debugging. Chains with no
|
|
4672
|
-
* receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
|
|
4678
|
+
* receive prerequisite (EVM, Solana, Sui, Aptos, Tron, and native TON/NEAR) never throw it.
|
|
4673
4679
|
*/
|
|
4674
4680
|
declare class RecipientNotReadyError extends PipRailError {
|
|
4675
4681
|
readonly code = "RECIPIENT_NOT_READY";
|
|
@@ -4766,7 +4772,7 @@ declare class NonReplayableBodyError extends PipRailError {
|
|
|
4766
4772
|
}
|
|
4767
4773
|
/**
|
|
4768
4774
|
* The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
|
|
4769
|
-
* Sui, NEAR) but the wallet, payTo, or token was given in another family's form
|
|
4775
|
+
* Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
|
|
4770
4776
|
* (e.g. an `0x…` payTo on Solana, or a `{ mint }` token on a Stellar chain).
|
|
4771
4777
|
*/
|
|
4772
4778
|
declare class WrongFamilyError extends PipRailError {
|
|
@@ -4778,7 +4784,8 @@ declare class WrongFamilyError extends PipRailError {
|
|
|
4778
4784
|
* token by full descriptor ({ address, decimals } EVM/Tron · { mint, decimals }
|
|
4779
4785
|
* Solana · { master, decimals } TON · { issuer, code, decimals } Stellar ·
|
|
4780
4786
|
* { issuer, currencyHex, decimals } XRPL · { coinType, decimals } Sui ·
|
|
4781
|
-
* { contractId, decimals } NEAR
|
|
4787
|
+
* { contractId, decimals } NEAR · { metadata, decimals } Aptos ·
|
|
4788
|
+
* { assetId, decimals } Algorand).
|
|
4782
4789
|
*/
|
|
4783
4790
|
declare class UnknownTokenError extends PipRailError {
|
|
4784
4791
|
readonly code = "UNKNOWN_TOKEN";
|
|
@@ -4790,7 +4797,8 @@ declare class UnknownTokenError extends PipRailError {
|
|
|
4790
4797
|
* `npm install @ton/ton @ton/core @ton/crypto`; Stellar:
|
|
4791
4798
|
* `npm install @stellar/stellar-sdk`; XRPL: `npm install xrpl`; Tron:
|
|
4792
4799
|
* `npm install tronweb`; Sui: `npm install @mysten/sui`; NEAR:
|
|
4793
|
-
* `npm install near-api-js
|
|
4800
|
+
* `npm install near-api-js`; Aptos: `npm install @aptos-labs/ts-sdk`;
|
|
4801
|
+
* Algorand: `npm install algosdk`.
|
|
4794
4802
|
*/
|
|
4795
4803
|
declare class MissingDriverError extends PipRailError {
|
|
4796
4804
|
readonly code = "MISSING_DRIVER";
|
package/dist/index.d.ts
CHANGED
|
@@ -3845,7 +3845,7 @@ interface AlgorandToken {
|
|
|
3845
3845
|
}
|
|
3846
3846
|
/**
|
|
3847
3847
|
* What to be paid in. Each driver validates the forms it accepts:
|
|
3848
|
-
* - 'native' the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
|
|
3848
|
+
* - 'native' the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP, TRX, NEAR, SUI, APT, ALGO)
|
|
3849
3849
|
* - 'USDC' (string) a symbol resolved against the chosen chain
|
|
3850
3850
|
* - EvmToken any ERC-20 (EVM chains)
|
|
3851
3851
|
* - SolanaToken any SPL token (Solana)
|
|
@@ -4130,6 +4130,8 @@ type PipRailEvent = {
|
|
|
4130
4130
|
* - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
|
|
4131
4131
|
* - XRPL → `{ seed }` (s… seed) or a ready `{ wallet }`
|
|
4132
4132
|
* - NEAR → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
|
|
4133
|
+
* - Aptos → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
|
|
4134
|
+
* - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
|
|
4133
4135
|
*/
|
|
4134
4136
|
type WalletInput = {
|
|
4135
4137
|
privateKey: string;
|
|
@@ -4263,7 +4265,7 @@ interface PipRailClientOptions {
|
|
|
4263
4265
|
/** Wallet for the chosen chain family. */
|
|
4264
4266
|
wallet: WalletInput;
|
|
4265
4267
|
/** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
|
|
4266
|
-
* 'xrpl', 'tron', 'sui', or '
|
|
4268
|
+
* 'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
|
|
4267
4269
|
chain: ChainSelector;
|
|
4268
4270
|
/** Override the chain's default RPC URL (recommended in production). */
|
|
4269
4271
|
rpcUrl?: string;
|
|
@@ -4441,8 +4443,10 @@ interface AgentTool {
|
|
|
4441
4443
|
invoke: (args: Record<string, unknown>) => Promise<unknown>;
|
|
4442
4444
|
}
|
|
4443
4445
|
/**
|
|
4444
|
-
*
|
|
4446
|
+
* Three tools wrapping a configured {@link PipRailClient}:
|
|
4445
4447
|
* - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
|
|
4448
|
+
* - `piprail_plan_payment(url)` — check you CAN pay (balance + gas + recipient
|
|
4449
|
+
* readiness) across every rail the URL offers, WITHOUT paying.
|
|
4446
4450
|
* - `piprail_pay_request(url, method?, body?)` — pay if needed and return the result.
|
|
4447
4451
|
*
|
|
4448
4452
|
* A policy/approval refusal comes back as a structured `{ declined: true, reason }`
|
|
@@ -4478,7 +4482,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
|
|
|
4478
4482
|
*/
|
|
4479
4483
|
interface AcceptOption {
|
|
4480
4484
|
/** Which chain. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar', 'xrpl',
|
|
4481
|
-
* 'tron', 'near', or '
|
|
4485
|
+
* 'tron', 'near', 'sui', 'aptos', or 'algorand'. */
|
|
4482
4486
|
chain: ChainSelector;
|
|
4483
4487
|
/** Token to be paid in (symbol / 'native' / custom descriptor). */
|
|
4484
4488
|
token: TokenInput;
|
|
@@ -4492,8 +4496,9 @@ interface AcceptOption {
|
|
|
4492
4496
|
interface RequirePaymentOptions {
|
|
4493
4497
|
/**
|
|
4494
4498
|
* Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
|
|
4495
|
-
* 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near',
|
|
4496
|
-
* `chain` + `token` + `amount`, OR use the multi-chain
|
|
4499
|
+
* 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', 'sui', 'aptos', or
|
|
4500
|
+
* 'algorand'. Provide `chain` + `token` + `amount`, OR use the multi-chain
|
|
4501
|
+
* `accept` array below.
|
|
4497
4502
|
*/
|
|
4498
4503
|
chain?: ChainSelector;
|
|
4499
4504
|
/** Override the chain's default RPC URL (recommended in production). */
|
|
@@ -4504,9 +4509,10 @@ interface RequirePaymentOptions {
|
|
|
4504
4509
|
* `{ address, decimals }` on EVM/Tron, `{ mint, decimals }` on Solana,
|
|
4505
4510
|
* `{ master, decimals }` on TON, `{ issuer, code, decimals }` on Stellar,
|
|
4506
4511
|
* `{ issuer, currencyHex, decimals }` on XRPL, `{ contractId, decimals }` on
|
|
4507
|
-
* NEAR, `{ coinType, decimals }` on Sui
|
|
4512
|
+
* NEAR, `{ coinType, decimals }` on Sui, `{ metadata, decimals }` on Aptos, or
|
|
4513
|
+
* `{ assetId, decimals }` on Algorand. You name the token; the SDK fills in
|
|
4508
4514
|
* the contract + decimals for built-in symbols. (Note: native USDC doesn't
|
|
4509
|
-
* exist on TON/Tron — USDT does; NEAR is
|
|
4515
|
+
* exist on TON/Tron — USDT does; native NEAR is supported via `'native'`.)
|
|
4510
4516
|
*/
|
|
4511
4517
|
token?: TokenInput;
|
|
4512
4518
|
/** Human-readable amount, e.g. "0.05" (single-chain form). */
|
|
@@ -4518,8 +4524,8 @@ interface RequirePaymentOptions {
|
|
|
4518
4524
|
*/
|
|
4519
4525
|
accept?: AcceptOption[];
|
|
4520
4526
|
/** Address that receives the payment (0x… EVM/Sui, base58 Solana, EQ…/UQ… TON,
|
|
4521
|
-
* G… Stellar, r… XRPL, T… Tron, account id on NEAR
|
|
4522
|
-
* form; the per-option fallback for the multi form. */
|
|
4527
|
+
* G… Stellar, r… XRPL, T… Tron, account id on NEAR, 0x… Aptos, base32 Algorand).
|
|
4528
|
+
* Required for the single form; the per-option fallback for the multi form. */
|
|
4523
4529
|
payTo?: AddressId;
|
|
4524
4530
|
/** Shown to the agent in the challenge. */
|
|
4525
4531
|
description?: string;
|
|
@@ -4669,7 +4675,7 @@ declare class InsufficientFundsError extends PipRailError {
|
|
|
4669
4675
|
* The message states the requirement and the fix in plain language **and echoes
|
|
4670
4676
|
* the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
|
|
4671
4677
|
* chain error is preserved on `.cause` for deeper debugging. Chains with no
|
|
4672
|
-
* receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
|
|
4678
|
+
* receive prerequisite (EVM, Solana, Sui, Aptos, Tron, and native TON/NEAR) never throw it.
|
|
4673
4679
|
*/
|
|
4674
4680
|
declare class RecipientNotReadyError extends PipRailError {
|
|
4675
4681
|
readonly code = "RECIPIENT_NOT_READY";
|
|
@@ -4766,7 +4772,7 @@ declare class NonReplayableBodyError extends PipRailError {
|
|
|
4766
4772
|
}
|
|
4767
4773
|
/**
|
|
4768
4774
|
* The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
|
|
4769
|
-
* Sui, NEAR) but the wallet, payTo, or token was given in another family's form
|
|
4775
|
+
* Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
|
|
4770
4776
|
* (e.g. an `0x…` payTo on Solana, or a `{ mint }` token on a Stellar chain).
|
|
4771
4777
|
*/
|
|
4772
4778
|
declare class WrongFamilyError extends PipRailError {
|
|
@@ -4778,7 +4784,8 @@ declare class WrongFamilyError extends PipRailError {
|
|
|
4778
4784
|
* token by full descriptor ({ address, decimals } EVM/Tron · { mint, decimals }
|
|
4779
4785
|
* Solana · { master, decimals } TON · { issuer, code, decimals } Stellar ·
|
|
4780
4786
|
* { issuer, currencyHex, decimals } XRPL · { coinType, decimals } Sui ·
|
|
4781
|
-
* { contractId, decimals } NEAR
|
|
4787
|
+
* { contractId, decimals } NEAR · { metadata, decimals } Aptos ·
|
|
4788
|
+
* { assetId, decimals } Algorand).
|
|
4782
4789
|
*/
|
|
4783
4790
|
declare class UnknownTokenError extends PipRailError {
|
|
4784
4791
|
readonly code = "UNKNOWN_TOKEN";
|
|
@@ -4790,7 +4797,8 @@ declare class UnknownTokenError extends PipRailError {
|
|
|
4790
4797
|
* `npm install @ton/ton @ton/core @ton/crypto`; Stellar:
|
|
4791
4798
|
* `npm install @stellar/stellar-sdk`; XRPL: `npm install xrpl`; Tron:
|
|
4792
4799
|
* `npm install tronweb`; Sui: `npm install @mysten/sui`; NEAR:
|
|
4793
|
-
* `npm install near-api-js
|
|
4800
|
+
* `npm install near-api-js`; Aptos: `npm install @aptos-labs/ts-sdk`;
|
|
4801
|
+
* Algorand: `npm install algosdk`.
|
|
4794
4802
|
*/
|
|
4795
4803
|
declare class MissingDriverError extends PipRailError {
|
|
4796
4804
|
readonly code = "MISSING_DRIVER";
|
package/dist/index.js
CHANGED
|
@@ -733,7 +733,7 @@ function makeEvmNetwork(resolved) {
|
|
|
733
733
|
}
|
|
734
734
|
return { token, native };
|
|
735
735
|
},
|
|
736
|
-
//
|
|
736
|
+
// No receive prerequisite — any 0x address receives native or ERC-20 immediately.
|
|
737
737
|
async recipientReady() {
|
|
738
738
|
return { ready: "n/a" };
|
|
739
739
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@piprail/sdk",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.1",
|
|
4
4
|
"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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
@@ -82,13 +82,13 @@
|
|
|
82
82
|
"peerDependencies": {
|
|
83
83
|
"@aptos-labs/ts-sdk": ">=2 <8",
|
|
84
84
|
"@mysten/sui": ">=2 <3",
|
|
85
|
-
"algosdk": ">=3 <4",
|
|
86
85
|
"@solana/spl-token": "^0.4.0",
|
|
87
86
|
"@solana/web3.js": "^1.95.0",
|
|
88
87
|
"@stellar/stellar-sdk": ">=13 <16",
|
|
89
88
|
"@ton/core": ">=0.59 <1",
|
|
90
89
|
"@ton/crypto": ">=3 <4",
|
|
91
90
|
"@ton/ton": ">=15 <17",
|
|
91
|
+
"algosdk": ">=3 <4",
|
|
92
92
|
"bs58": "^5.0.0",
|
|
93
93
|
"near-api-js": ">=7 <8",
|
|
94
94
|
"tronweb": ">=6 <7",
|