@xona-labs/xpay 0.1.0

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.
Files changed (143) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -0
  3. package/dist/cli/accounts.d.ts +13 -0
  4. package/dist/cli/accounts.d.ts.map +1 -0
  5. package/dist/cli/accounts.js +66 -0
  6. package/dist/cli/accounts.js.map +1 -0
  7. package/dist/cli/balance.d.ts +14 -0
  8. package/dist/cli/balance.d.ts.map +1 -0
  9. package/dist/cli/balance.js +60 -0
  10. package/dist/cli/balance.js.map +1 -0
  11. package/dist/cli/common.d.ts +20 -0
  12. package/dist/cli/common.d.ts.map +1 -0
  13. package/dist/cli/common.js +58 -0
  14. package/dist/cli/common.js.map +1 -0
  15. package/dist/cli/discover.d.ts +12 -0
  16. package/dist/cli/discover.d.ts.map +1 -0
  17. package/dist/cli/discover.js +69 -0
  18. package/dist/cli/discover.js.map +1 -0
  19. package/dist/cli/guardrail.d.ts +16 -0
  20. package/dist/cli/guardrail.d.ts.map +1 -0
  21. package/dist/cli/guardrail.js +71 -0
  22. package/dist/cli/guardrail.js.map +1 -0
  23. package/dist/cli/history.d.ts +16 -0
  24. package/dist/cli/history.d.ts.map +1 -0
  25. package/dist/cli/history.js +59 -0
  26. package/dist/cli/history.js.map +1 -0
  27. package/dist/cli/index.d.ts +17 -0
  28. package/dist/cli/index.d.ts.map +1 -0
  29. package/dist/cli/index.js +165 -0
  30. package/dist/cli/index.js.map +1 -0
  31. package/dist/cli/init.d.ts +23 -0
  32. package/dist/cli/init.d.ts.map +1 -0
  33. package/dist/cli/init.js +114 -0
  34. package/dist/cli/init.js.map +1 -0
  35. package/dist/cli/mcp-server.d.ts +26 -0
  36. package/dist/cli/mcp-server.d.ts.map +1 -0
  37. package/dist/cli/mcp-server.js +112 -0
  38. package/dist/cli/mcp-server.js.map +1 -0
  39. package/dist/cli/pay.d.ts +15 -0
  40. package/dist/cli/pay.d.ts.map +1 -0
  41. package/dist/cli/pay.js +76 -0
  42. package/dist/cli/pay.js.map +1 -0
  43. package/dist/cli/transfer.d.ts +19 -0
  44. package/dist/cli/transfer.d.ts.map +1 -0
  45. package/dist/cli/transfer.js +66 -0
  46. package/dist/cli/transfer.js.map +1 -0
  47. package/dist/discover/cache.d.ts +24 -0
  48. package/dist/discover/cache.d.ts.map +1 -0
  49. package/dist/discover/cache.js +94 -0
  50. package/dist/discover/cache.js.map +1 -0
  51. package/dist/discover/index.d.ts +21 -0
  52. package/dist/discover/index.d.ts.map +1 -0
  53. package/dist/discover/index.js +88 -0
  54. package/dist/discover/index.js.map +1 -0
  55. package/dist/discover/payai.d.ts +18 -0
  56. package/dist/discover/payai.d.ts.map +1 -0
  57. package/dist/discover/payai.js +56 -0
  58. package/dist/discover/payai.js.map +1 -0
  59. package/dist/do/index.d.ts +17 -0
  60. package/dist/do/index.d.ts.map +1 -0
  61. package/dist/do/index.js +32 -0
  62. package/dist/do/index.js.map +1 -0
  63. package/dist/guardrail/index.d.ts +47 -0
  64. package/dist/guardrail/index.d.ts.map +1 -0
  65. package/dist/guardrail/index.js +99 -0
  66. package/dist/guardrail/index.js.map +1 -0
  67. package/dist/history/evm.d.ts +21 -0
  68. package/dist/history/evm.d.ts.map +1 -0
  69. package/dist/history/evm.js +118 -0
  70. package/dist/history/evm.js.map +1 -0
  71. package/dist/history/index.d.ts +19 -0
  72. package/dist/history/index.d.ts.map +1 -0
  73. package/dist/history/index.js +45 -0
  74. package/dist/history/index.js.map +1 -0
  75. package/dist/history/solana.d.ts +20 -0
  76. package/dist/history/solana.d.ts.map +1 -0
  77. package/dist/history/solana.js +97 -0
  78. package/dist/history/solana.js.map +1 -0
  79. package/dist/history/types.d.ts +26 -0
  80. package/dist/history/types.d.ts.map +1 -0
  81. package/dist/history/types.js +10 -0
  82. package/dist/history/types.js.map +1 -0
  83. package/dist/index.d.ts +94 -0
  84. package/dist/index.d.ts.map +1 -0
  85. package/dist/index.js +74 -0
  86. package/dist/index.js.map +1 -0
  87. package/dist/profile/derive.d.ts +28 -0
  88. package/dist/profile/derive.d.ts.map +1 -0
  89. package/dist/profile/derive.js +75 -0
  90. package/dist/profile/derive.js.map +1 -0
  91. package/dist/profile/index.d.ts +74 -0
  92. package/dist/profile/index.d.ts.map +1 -0
  93. package/dist/profile/index.js +115 -0
  94. package/dist/profile/index.js.map +1 -0
  95. package/dist/profile/storage.d.ts +35 -0
  96. package/dist/profile/storage.d.ts.map +1 -0
  97. package/dist/profile/storage.js +162 -0
  98. package/dist/profile/storage.js.map +1 -0
  99. package/dist/profile/types.d.ts +69 -0
  100. package/dist/profile/types.d.ts.map +1 -0
  101. package/dist/profile/types.js +9 -0
  102. package/dist/profile/types.js.map +1 -0
  103. package/dist/signers/index.d.ts +5 -0
  104. package/dist/signers/index.d.ts.map +1 -0
  105. package/dist/signers/index.js +5 -0
  106. package/dist/signers/index.js.map +1 -0
  107. package/dist/signers/phantom.d.ts +14 -0
  108. package/dist/signers/phantom.d.ts.map +1 -0
  109. package/dist/signers/phantom.js +12 -0
  110. package/dist/signers/phantom.js.map +1 -0
  111. package/dist/signers/privy.d.ts +20 -0
  112. package/dist/signers/privy.d.ts.map +1 -0
  113. package/dist/signers/privy.js +15 -0
  114. package/dist/signers/privy.js.map +1 -0
  115. package/dist/signers/raw-evm.d.ts +15 -0
  116. package/dist/signers/raw-evm.d.ts.map +1 -0
  117. package/dist/signers/raw-evm.js +70 -0
  118. package/dist/signers/raw-evm.js.map +1 -0
  119. package/dist/signers/raw-solana.d.ts +15 -0
  120. package/dist/signers/raw-solana.d.ts.map +1 -0
  121. package/dist/signers/raw-solana.js +88 -0
  122. package/dist/signers/raw-solana.js.map +1 -0
  123. package/dist/tools/index.d.ts +48 -0
  124. package/dist/tools/index.d.ts.map +1 -0
  125. package/dist/tools/index.js +164 -0
  126. package/dist/tools/index.js.map +1 -0
  127. package/dist/transfer/index.d.ts +30 -0
  128. package/dist/transfer/index.d.ts.map +1 -0
  129. package/dist/transfer/index.js +86 -0
  130. package/dist/transfer/index.js.map +1 -0
  131. package/dist/types.d.ts +203 -0
  132. package/dist/types.d.ts.map +1 -0
  133. package/dist/types.js +56 -0
  134. package/dist/types.js.map +1 -0
  135. package/dist/use/index.d.ts +38 -0
  136. package/dist/use/index.d.ts.map +1 -0
  137. package/dist/use/index.js +173 -0
  138. package/dist/use/index.js.map +1 -0
  139. package/dist/wallet/index.d.ts +31 -0
  140. package/dist/wallet/index.d.ts.map +1 -0
  141. package/dist/wallet/index.js +56 -0
  142. package/dist/wallet/index.js.map +1 -0
  143. package/package.json +70 -0
@@ -0,0 +1,164 @@
1
+ /**
2
+ * LLM tool-definition exporters.
3
+ *
4
+ * Each helper returns the tool/function-calling schema in the vendor's
5
+ * preferred shape plus a `handlers` map. Wire them into your agent loop:
6
+ *
7
+ * const { tools, handlers } = forClaude(xpay);
8
+ * // pass `tools` to Anthropic, look up `handlers[name]` on tool_use blocks.
9
+ *
10
+ * The tool surface mirrors the CLI commands so an agent's mental model is
11
+ * the same whether it's calling the SDK, the CLI, or MCP.
12
+ */
13
+ /** Anthropic Claude tool definitions. */
14
+ export function forClaude(xpay) {
15
+ const tools = [
16
+ {
17
+ name: "xpay_discover",
18
+ description: "Find paid HTTP services across the agentic-commerce catalog (PayAI + others). " +
19
+ "Returns ranked candidates with price, network, and payment recipient.",
20
+ input_schema: {
21
+ type: "object",
22
+ properties: {
23
+ query: { type: "string", description: "What you want to find, in natural language." },
24
+ limit: { type: "number", description: "Max results. Default 5." },
25
+ network: { type: "string", description: "Restrict to one network (solana, base, ...)." },
26
+ },
27
+ required: ["query"],
28
+ },
29
+ },
30
+ {
31
+ name: "xpay_use",
32
+ description: "Call a specific resource (by URL) from the catalog. Handles x402 payment automatically.",
33
+ input_schema: {
34
+ type: "object",
35
+ properties: {
36
+ resourceUrl: { type: "string", description: "URL of the resource to call." },
37
+ body: { type: "object", description: "Optional JSON body for POST endpoints." },
38
+ },
39
+ required: ["resourceUrl"],
40
+ },
41
+ },
42
+ {
43
+ name: "xpay_do",
44
+ description: "Discover the best service for an intent and call it in one step. " +
45
+ "Use this when you don't need to compare options first.",
46
+ input_schema: {
47
+ type: "object",
48
+ properties: {
49
+ query: { type: "string" },
50
+ body: { type: "object" },
51
+ },
52
+ required: ["query"],
53
+ },
54
+ },
55
+ {
56
+ name: "xpay_transfer",
57
+ description: "Send USDC directly to an address (no x402, no provider). Subject to the user's guardrail.",
58
+ input_schema: {
59
+ type: "object",
60
+ properties: {
61
+ amount: { type: "number", description: "USDC amount in human units, e.g. 1.5 for $1.50." },
62
+ to: { type: "string", description: "Recipient address (Solana base58 or EVM 0x...)." },
63
+ network: { type: "string", description: "Force network if address is ambiguous." },
64
+ },
65
+ required: ["amount", "to"],
66
+ },
67
+ },
68
+ {
69
+ name: "xpay_balance",
70
+ description: "USDC balance on each configured network, plus a total.",
71
+ input_schema: {
72
+ type: "object",
73
+ properties: {
74
+ network: { type: "string", description: "Restrict to one network." },
75
+ },
76
+ },
77
+ },
78
+ {
79
+ name: "xpay_history",
80
+ description: "Recent USDC activity across all configured networks (send + receive), sorted newest first.",
81
+ input_schema: {
82
+ type: "object",
83
+ properties: {
84
+ limit: { type: "number", description: "Max entries. Default 25." },
85
+ network: { type: "string", description: "Restrict to one network." },
86
+ },
87
+ },
88
+ },
89
+ {
90
+ name: "xpay_guardrail",
91
+ description: "Read the active spending guardrail (caps, allowed hosts, approval threshold).",
92
+ input_schema: { type: "object", properties: {} },
93
+ },
94
+ ];
95
+ const handlers = {
96
+ xpay_discover: async (input) => xpay.discover({
97
+ query: input.query,
98
+ limit: input.limit ?? 5,
99
+ networks: input.network ? [input.network] : undefined,
100
+ }),
101
+ xpay_use: async (input) => {
102
+ const url = input.resourceUrl;
103
+ return xpay.useByUrl(url, { body: input.body });
104
+ },
105
+ xpay_do: async (input) => xpay.do(input.query, { body: input.body }),
106
+ xpay_transfer: async (input) => xpay.transfer({
107
+ amount: input.amount,
108
+ to: input.to,
109
+ network: input.network,
110
+ token: "USDC",
111
+ }),
112
+ xpay_balance: async (input) => {
113
+ const networks = input.network
114
+ ? [input.network]
115
+ : xpay.wallet.networks;
116
+ const out = {};
117
+ let total = 0;
118
+ for (const n of networks) {
119
+ const b = await xpay.wallet.balance(n);
120
+ out[n] = b;
121
+ total += b;
122
+ }
123
+ return { perNetwork: out, totalUsdc: total };
124
+ },
125
+ xpay_history: async (input) => xpay.history({
126
+ limit: input.limit ?? 25,
127
+ networks: input.network ? [input.network] : undefined,
128
+ }),
129
+ xpay_guardrail: async () => xpay.guardrail,
130
+ };
131
+ return { tools, handlers };
132
+ }
133
+ /** OpenAI function-calling tool definitions (derived from the Claude shape). */
134
+ export function forOpenAI(xpay) {
135
+ const claude = forClaude(xpay);
136
+ return {
137
+ tools: claude.tools.map((t) => ({
138
+ type: "function",
139
+ function: {
140
+ name: t.name,
141
+ description: t.description,
142
+ parameters: t.input_schema,
143
+ },
144
+ })),
145
+ handlers: claude.handlers,
146
+ };
147
+ }
148
+ /** Google Gemini function-declaration definitions. */
149
+ export function forGemini(xpay) {
150
+ const claude = forClaude(xpay);
151
+ return {
152
+ tools: [
153
+ {
154
+ functionDeclarations: claude.tools.map((t) => ({
155
+ name: t.name,
156
+ description: t.description,
157
+ parameters: t.input_schema,
158
+ })),
159
+ },
160
+ ],
161
+ handlers: claude.handlers,
162
+ };
163
+ }
164
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Direct USDC transfer — no x402, no provider, just send funds.
3
+ *
4
+ * Goes through the same guardrail as `use()` so a compromised CLI / agent
5
+ * can't drain the wallet past the configured caps. v1 supports USDC only.
6
+ */
7
+ import type { Network } from "../types.js";
8
+ import type { Wallet } from "../wallet/index.js";
9
+ import type { Guardrail } from "../guardrail/index.js";
10
+ export interface TransferArgs {
11
+ /** Human amount (e.g. 5 means $5.00 USDC). */
12
+ amount: number;
13
+ /** Recipient address. Format implies the network unless overridden. */
14
+ to: string;
15
+ /** Force a specific network (required if the wallet has >1 EVM signer). */
16
+ network?: Network;
17
+ /** v1 only supports "USDC" — leaving it explicit for future-proofing. */
18
+ token?: "USDC";
19
+ wallet: Wallet;
20
+ guardrail: Guardrail;
21
+ }
22
+ export interface TransferResult {
23
+ network: Network;
24
+ txSig: string;
25
+ amount: number;
26
+ token: "USDC";
27
+ to: string;
28
+ }
29
+ export declare function transfer(args: TransferArgs): Promise<TransferResult>;
30
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAsB,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAWvD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CA0C1E"}
@@ -0,0 +1,86 @@
1
+ /**
2
+ * Direct USDC transfer — no x402, no provider, just send funds.
3
+ *
4
+ * Goes through the same guardrail as `use()` so a compromised CLI / agent
5
+ * can't drain the wallet past the configured caps. v1 supports USDC only.
6
+ */
7
+ /** Mint / contract addresses for the only token we support in v1. */
8
+ const USDC_ASSETS = {
9
+ solana: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
10
+ base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
11
+ ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
12
+ arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
13
+ optimism: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
14
+ };
15
+ export async function transfer(args) {
16
+ const token = (args.token ?? "USDC").toUpperCase();
17
+ if (token !== "USDC") {
18
+ throw new Error(`transfer: only USDC supported in v1 (got "${token}")`);
19
+ }
20
+ if (!(args.amount > 0)) {
21
+ throw new Error(`transfer: amount must be > 0`);
22
+ }
23
+ const network = resolveNetwork(args);
24
+ const asset = USDC_ASSETS[network];
25
+ if (!asset)
26
+ throw new Error(`transfer: no USDC address registered for "${network}"`);
27
+ // USDC has 6 decimals on every chain we touch.
28
+ const atoms = BigInt(Math.round(args.amount * 1_000_000)).toString();
29
+ // Build a PaymentRequirement so the guardrail and signer code paths stay
30
+ // identical to x402 `use()`. The guardrail's "resource" is synthetic — we
31
+ // pretend the destination address is the host so allowedHosts can still gate
32
+ // transfers (admin-only addresses, treasuries, etc).
33
+ const requirement = {
34
+ asset,
35
+ payTo: args.to,
36
+ amount: atoms,
37
+ scheme: "exact",
38
+ network: networkToScheme(network),
39
+ };
40
+ await args.guardrail.check({
41
+ resource: {
42
+ resource: `xpay://transfer/${network}/${args.to}`,
43
+ type: "transfer",
44
+ method: "POST",
45
+ accepts: [requirement],
46
+ },
47
+ requirement,
48
+ });
49
+ const signer = args.wallet.signer(network);
50
+ const txSig = await signer.pay(requirement);
51
+ return { network, txSig, amount: args.amount, token: "USDC", to: args.to };
52
+ }
53
+ /** Auto-detect the network from the address shape, with explicit override. */
54
+ function resolveNetwork(args) {
55
+ if (args.network) {
56
+ if (!args.wallet.has(args.network)) {
57
+ throw new Error(`transfer: no signer for network "${args.network}"`);
58
+ }
59
+ return args.network;
60
+ }
61
+ const looksLikeEvm = /^0x[0-9a-fA-F]{40}$/.test(args.to);
62
+ if (looksLikeEvm) {
63
+ const evm = ["base", "ethereum", "arbitrum", "optimism"].filter((n) => args.wallet.has(n));
64
+ if (evm.length === 0)
65
+ throw new Error(`transfer: address looks EVM but no EVM signer is configured`);
66
+ if (evm.length === 1)
67
+ return evm[0];
68
+ throw new Error(`transfer: address is EVM-shaped but wallet has multiple EVM networks (${evm.join(", ")}). Pass --network to disambiguate.`);
69
+ }
70
+ // Default to Solana.
71
+ if (!args.wallet.has("solana")) {
72
+ throw new Error(`transfer: address looks Solana but no Solana signer is configured`);
73
+ }
74
+ return "solana";
75
+ }
76
+ /** PayAI / x402 schemes use eip155 strings for EVM. Convert for consistency. */
77
+ function networkToScheme(net) {
78
+ switch (net) {
79
+ case "base": return "eip155:8453";
80
+ case "ethereum": return "eip155:1";
81
+ case "arbitrum": return "eip155:42161";
82
+ case "optimism": return "eip155:10";
83
+ default: return net;
84
+ }
85
+ }
86
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Core types for xPay.
3
+ *
4
+ * The {@link Resource} shape mirrors PayAI's facilitator discovery format
5
+ * (https://facilitator.payai.network/discovery/resources) so we can ingest
6
+ * the broader x402 ecosystem without translation.
7
+ */
8
+ import { z } from "zod";
9
+ /** A network slug. Keep this open-ended so new chains can be added without an SDK release. */
10
+ export type Network = "solana" | "base" | "ethereum" | "arbitrum" | "optimism" | (string & {});
11
+ /**
12
+ * One payment option attached to a {@link Resource}.
13
+ *
14
+ * A resource may accept multiple options (e.g. USDC on Solana OR USDC on Base);
15
+ * the {@link use} module picks the best one based on wallet balance + fees.
16
+ */
17
+ export declare const PaymentRequirementSchema: z.ZodObject<{
18
+ /** Token mint (Solana) or contract address (EVM). */
19
+ asset: z.ZodString;
20
+ /** Recipient address. */
21
+ payTo: z.ZodString;
22
+ /** Atomic amount as a string (lamports, wei, or token base units). */
23
+ amount: z.ZodOptional<z.ZodString>;
24
+ /** x402 scheme, typically `"exact"`. */
25
+ scheme: z.ZodString;
26
+ /** Network slug. PayAI uses `"solana"` or EIP-155 strings like `"eip155:8453"`. */
27
+ network: z.ZodString;
28
+ /** Seconds before the payment intent expires. */
29
+ maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
30
+ mimeType: z.ZodOptional<z.ZodString>;
31
+ extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
32
+ /** Some PayAI entries duplicate the resource URL inside `accepts[]`. */
33
+ resource: z.ZodOptional<z.ZodString>;
34
+ }, "strip", z.ZodTypeAny, {
35
+ asset: string;
36
+ payTo: string;
37
+ scheme: string;
38
+ network: string;
39
+ amount?: string | undefined;
40
+ maxTimeoutSeconds?: number | undefined;
41
+ mimeType?: string | undefined;
42
+ extra?: Record<string, unknown> | undefined;
43
+ resource?: string | undefined;
44
+ }, {
45
+ asset: string;
46
+ payTo: string;
47
+ scheme: string;
48
+ network: string;
49
+ amount?: string | undefined;
50
+ maxTimeoutSeconds?: number | undefined;
51
+ mimeType?: string | undefined;
52
+ extra?: Record<string, unknown> | undefined;
53
+ resource?: string | undefined;
54
+ }>;
55
+ export type PaymentRequirement = z.infer<typeof PaymentRequirementSchema>;
56
+ /**
57
+ * A discoverable paid HTTP resource.
58
+ *
59
+ * Shape intentionally matches PayAI's discovery item so we can stream their
60
+ * `items[]` straight through. Other catalogs (Pay, Coinbase) are adapted into
61
+ * this shape at the source.
62
+ */
63
+ export declare const ResourceSchema: z.ZodObject<{
64
+ /** Fully-qualified URL the agent ultimately calls. */
65
+ resource: z.ZodString;
66
+ /** Always `"http"` today; reserved for future transports. */
67
+ type: z.ZodString;
68
+ /** HTTP method to invoke. */
69
+ method: z.ZodDefault<z.ZodString>;
70
+ /** x402 protocol version of this listing. */
71
+ x402Version: z.ZodOptional<z.ZodNumber>;
72
+ /** All accepted payment options. */
73
+ accepts: z.ZodDefault<z.ZodArray<z.ZodObject<{
74
+ /** Token mint (Solana) or contract address (EVM). */
75
+ asset: z.ZodString;
76
+ /** Recipient address. */
77
+ payTo: z.ZodString;
78
+ /** Atomic amount as a string (lamports, wei, or token base units). */
79
+ amount: z.ZodOptional<z.ZodString>;
80
+ /** x402 scheme, typically `"exact"`. */
81
+ scheme: z.ZodString;
82
+ /** Network slug. PayAI uses `"solana"` or EIP-155 strings like `"eip155:8453"`. */
83
+ network: z.ZodString;
84
+ /** Seconds before the payment intent expires. */
85
+ maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
86
+ mimeType: z.ZodOptional<z.ZodString>;
87
+ extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
88
+ /** Some PayAI entries duplicate the resource URL inside `accepts[]`. */
89
+ resource: z.ZodOptional<z.ZodString>;
90
+ }, "strip", z.ZodTypeAny, {
91
+ asset: string;
92
+ payTo: string;
93
+ scheme: string;
94
+ network: string;
95
+ amount?: string | undefined;
96
+ maxTimeoutSeconds?: number | undefined;
97
+ mimeType?: string | undefined;
98
+ extra?: Record<string, unknown> | undefined;
99
+ resource?: string | undefined;
100
+ }, {
101
+ asset: string;
102
+ payTo: string;
103
+ scheme: string;
104
+ network: string;
105
+ amount?: string | undefined;
106
+ maxTimeoutSeconds?: number | undefined;
107
+ mimeType?: string | undefined;
108
+ extra?: Record<string, unknown> | undefined;
109
+ resource?: string | undefined;
110
+ }>, "many">>;
111
+ lastUpdated: z.ZodOptional<z.ZodString>;
112
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
113
+ inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
114
+ outputSchema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
115
+ }, "strip", z.ZodTypeAny, {
116
+ type: string;
117
+ resource: string;
118
+ method: string;
119
+ accepts: {
120
+ asset: string;
121
+ payTo: string;
122
+ scheme: string;
123
+ network: string;
124
+ amount?: string | undefined;
125
+ maxTimeoutSeconds?: number | undefined;
126
+ mimeType?: string | undefined;
127
+ extra?: Record<string, unknown> | undefined;
128
+ resource?: string | undefined;
129
+ }[];
130
+ x402Version?: number | undefined;
131
+ lastUpdated?: string | undefined;
132
+ metadata?: Record<string, unknown> | undefined;
133
+ inputSchema?: Record<string, unknown> | undefined;
134
+ outputSchema?: Record<string, unknown> | null | undefined;
135
+ }, {
136
+ type: string;
137
+ resource: string;
138
+ method?: string | undefined;
139
+ x402Version?: number | undefined;
140
+ accepts?: {
141
+ asset: string;
142
+ payTo: string;
143
+ scheme: string;
144
+ network: string;
145
+ amount?: string | undefined;
146
+ maxTimeoutSeconds?: number | undefined;
147
+ mimeType?: string | undefined;
148
+ extra?: Record<string, unknown> | undefined;
149
+ resource?: string | undefined;
150
+ }[] | undefined;
151
+ lastUpdated?: string | undefined;
152
+ metadata?: Record<string, unknown> | undefined;
153
+ inputSchema?: Record<string, unknown> | undefined;
154
+ outputSchema?: Record<string, unknown> | null | undefined;
155
+ }>;
156
+ export type Resource = z.infer<typeof ResourceSchema>;
157
+ /** Result returned by {@link XPay.use}. */
158
+ export interface UseResult {
159
+ /** Decoded response body (JSON if possible, else string). */
160
+ data: unknown;
161
+ /** Raw HTTP status from the upstream provider. */
162
+ status: number;
163
+ /** Network the payment settled on. */
164
+ network: Network;
165
+ /** Atomic amount paid. */
166
+ amountPaid: string;
167
+ /** Settlement signature / tx hash, if available. */
168
+ txSig?: string;
169
+ }
170
+ /** Options passed to {@link XPay.discover}. */
171
+ export interface DiscoverOptions {
172
+ /** Free-text query — matched against resource URL, metadata, and category. */
173
+ query?: string;
174
+ /** Restrict to specific networks. Defaults to all configured. */
175
+ networks?: Network[];
176
+ /** Max results to return. */
177
+ limit?: number;
178
+ /** Catalog sources to query. Defaults to all configured. */
179
+ sources?: CatalogSource[];
180
+ }
181
+ /** Built-in catalog sources. Custom sources can be plugged in by users. */
182
+ export type CatalogSource = "payai" | "pay" | "xona" | (string & {});
183
+ /** A configured signer for a single network. */
184
+ export interface Signer {
185
+ network: Network;
186
+ address: string;
187
+ /**
188
+ * Sign an arbitrary message (used for x402 payment authorization payloads).
189
+ * The exact bytes signed depend on the network — see implementations.
190
+ */
191
+ signMessage(message: Uint8Array): Promise<Uint8Array>;
192
+ /**
193
+ * Sign and broadcast a token transfer to satisfy a payment requirement.
194
+ * Returns the settlement signature / tx hash.
195
+ */
196
+ pay(req: PaymentRequirement): Promise<string>;
197
+ /**
198
+ * Optional: read the wallet's USDC balance (human units). Defaults to 0 if
199
+ * the signer doesn't implement it.
200
+ */
201
+ balance?(): Promise<number>;
202
+ }
203
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8FAA8F;AAC9F,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/F;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;IACnC,qDAAqD;;IAErD,yBAAyB;;IAEzB,sEAAsE;;IAEtE,wCAAwC;;IAExC,mFAAmF;;IAEnF,iDAAiD;;;;IAIjD,wEAAwE;;;;;;;;;;;;;;;;;;;;;;EAExE,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;IACzB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,6BAA6B;;IAE7B,6CAA6C;;IAE7C,oCAAoC;;QAnCpC,qDAAqD;;QAErD,yBAAyB;;QAEzB,sEAAsE;;QAEtE,wCAAwC;;QAExC,mFAAmF;;QAEnF,iDAAiD;;;;QAIjD,wEAAwE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BxE,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,2CAA2C;AAC3C,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,IAAI,EAAE,OAAO,CAAC;IACd,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAErE,gDAAgD;AAChD,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtD;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C;;;OAGG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B"}
package/dist/types.js ADDED
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Core types for xPay.
3
+ *
4
+ * The {@link Resource} shape mirrors PayAI's facilitator discovery format
5
+ * (https://facilitator.payai.network/discovery/resources) so we can ingest
6
+ * the broader x402 ecosystem without translation.
7
+ */
8
+ import { z } from "zod";
9
+ /**
10
+ * One payment option attached to a {@link Resource}.
11
+ *
12
+ * A resource may accept multiple options (e.g. USDC on Solana OR USDC on Base);
13
+ * the {@link use} module picks the best one based on wallet balance + fees.
14
+ */
15
+ export const PaymentRequirementSchema = z.object({
16
+ /** Token mint (Solana) or contract address (EVM). */
17
+ asset: z.string(),
18
+ /** Recipient address. */
19
+ payTo: z.string(),
20
+ /** Atomic amount as a string (lamports, wei, or token base units). */
21
+ amount: z.string().optional(),
22
+ /** x402 scheme, typically `"exact"`. */
23
+ scheme: z.string(),
24
+ /** Network slug. PayAI uses `"solana"` or EIP-155 strings like `"eip155:8453"`. */
25
+ network: z.string(),
26
+ /** Seconds before the payment intent expires. */
27
+ maxTimeoutSeconds: z.number().optional(),
28
+ mimeType: z.string().optional(),
29
+ extra: z.record(z.unknown()).optional(),
30
+ /** Some PayAI entries duplicate the resource URL inside `accepts[]`. */
31
+ resource: z.string().optional(),
32
+ });
33
+ /**
34
+ * A discoverable paid HTTP resource.
35
+ *
36
+ * Shape intentionally matches PayAI's discovery item so we can stream their
37
+ * `items[]` straight through. Other catalogs (Pay, Coinbase) are adapted into
38
+ * this shape at the source.
39
+ */
40
+ export const ResourceSchema = z.object({
41
+ /** Fully-qualified URL the agent ultimately calls. */
42
+ resource: z.string(),
43
+ /** Always `"http"` today; reserved for future transports. */
44
+ type: z.string(),
45
+ /** HTTP method to invoke. */
46
+ method: z.string().default("GET"),
47
+ /** x402 protocol version of this listing. */
48
+ x402Version: z.number().optional(),
49
+ /** All accepted payment options. */
50
+ accepts: z.array(PaymentRequirementSchema).default([]),
51
+ lastUpdated: z.string().optional(),
52
+ metadata: z.record(z.unknown()).optional(),
53
+ inputSchema: z.record(z.unknown()).optional(),
54
+ outputSchema: z.record(z.unknown()).nullable().optional(),
55
+ });
56
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,qDAAqD;IACrD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,yBAAyB;IACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,sEAAsE;IACtE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,wCAAwC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,mFAAmF;IACnF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,iDAAiD;IACjD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACvC,wEAAwE;IACxE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,sDAAsD;IACtD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,6DAA6D;IAC7D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,6BAA6B;IAC7B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACjC,6CAA6C;IAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,oCAAoC;IACpC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACtD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC7C,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC1D,CAAC,CAAC"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Use — call a paid resource, handling x402 payment end-to-end.
3
+ *
4
+ * Two modes:
5
+ * - **Catalog mode** (`resource` has `accepts[]`): we pick a requirement up
6
+ * front, run guardrail, pay, then call with the X-Payment header.
7
+ * - **Live challenge mode** (`resource.accepts` empty *or* `useByUrl()`): we
8
+ * call the URL first, expect a `402` with a body listing accepted payment
9
+ * options, then settle and retry. This is the canonical x402 v2 flow and
10
+ * lets agents pay resources they discovered *outside* of any catalog.
11
+ *
12
+ * Both paths converge on the same {@link UseResult}.
13
+ */
14
+ import { type Resource, type UseResult } from "../types.js";
15
+ import type { Wallet } from "../wallet/index.js";
16
+ import type { Guardrail } from "../guardrail/index.js";
17
+ export interface UseArgs {
18
+ resource: Resource;
19
+ wallet: Wallet;
20
+ guardrail: Guardrail;
21
+ body?: unknown;
22
+ headers?: Record<string, string>;
23
+ }
24
+ export declare function use(args: UseArgs): Promise<UseResult>;
25
+ /**
26
+ * Convenience: call any URL with x402 support. Agents can use this when they
27
+ * have a URL but no catalog entry — e.g. crawled from the web.
28
+ */
29
+ export interface UseByUrlArgs {
30
+ url: string;
31
+ method?: string;
32
+ wallet: Wallet;
33
+ guardrail: Guardrail;
34
+ body?: unknown;
35
+ headers?: Record<string, string>;
36
+ }
37
+ export declare function useByUrl(args: UseByUrlArgs): Promise<UseResult>;
38
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/use/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAO3D;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAcrE"}