{"_id":"@0xsupremedev/x402-sdk","_rev":"3-cfc738cb3e3ef27c4613b1ca0b94d4ee","name":"@0xsupremedev/x402-sdk","dist-tags":{"latest":"0.3.1"},"versions":{"0.2.0":{"name":"@0xsupremedev/x402-sdk","version":"0.2.0","keywords":["solana","x402","payments","ai-agents","sdk","web3","autonomous-agents"],"author":{"name":"Supreme Dev","email":"0xsupremedev@gmail.com"},"license":"MIT","_id":"@0xsupremedev/x402-sdk@0.2.0","maintainers":[{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"}],"dist":{"shasum":"b0db6f1594daa0e4ffd86ab99cfe3082d3edaecc","tarball":"https://registry.npmjs.org/@0xsupremedev/x402-sdk/-/x402-sdk-0.2.0.tgz","fileCount":11,"integrity":"sha512-uFi2LiDY9nyQaLumtJDPnfiPhSU/zW421NDj2hvmhe036jSrn2NEv3TyvB+O+NSBfb1m25EX2aEO339AK2/aeg==","signatures":[{"sig":"MEQCIHw91jOIbA+UmGxS0Dop0kAKFGH+9yAQ9vRSSFXeLDKhAiAKmfCwF/DJd9ttFqH3HsRdiqPVcMUpyb0YaXtzTkJsWg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23130},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","gitHead":"f46ffc54ce9689bdc08c33f8c88afd095133d2f9","scripts":{"lint":"eslint \"src/**/*.ts\"","test":"vitest run","build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"},"_npmVersion":"11.5.2","description":"SolWave x402 Protocol SDK for Solana: AI-powered agent-to-agent payments","directories":{"example":"examples"},"_nodeVersion":"22.18.0","dependencies":{"@solana/web3.js":"^1.98.4"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.0.0","vitest":"^2.1.0","ts-node":"^10.9.1","typescript":"^5.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/x402-sdk_0.2.0_1764231059716_0.5444199637209521","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@0xsupremedev/x402-sdk","version":"0.3.0","keywords":["solana","x402","payments","ai-agents","sdk","web3","autonomous-agents"],"author":{"name":"Supreme Dev","email":"0xsupremedev@gmail.com"},"license":"MIT","_id":"@0xsupremedev/x402-sdk@0.3.0","maintainers":[{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"}],"dist":{"shasum":"bebde50ae2dd7ccc4fa39ed36242cda8b1949d88","tarball":"https://registry.npmjs.org/@0xsupremedev/x402-sdk/-/x402-sdk-0.3.0.tgz","fileCount":23,"integrity":"sha512-r02XmmO3GYyRfGE73rEjwT8SlOeqbQTffH3I1YIycacExAIlB1t/kKsXmOlKis4SdsAoaVYPLL6zbpiVIpKtVw==","signatures":[{"sig":"MEYCIQCnlGas+OnjlwYvYR/1niQqivksVFV/Zlh3fjW2ewtcmgIhAPZx1/aLvTjxe9CxPOYedp4YzF4M//lc4QGm2z7S5dNS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36524},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","gitHead":"f46ffc54ce9689bdc08c33f8c88afd095133d2f9","scripts":{"lint":"eslint \"src/**/*.ts\"","test":"vitest run","build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"},"_npmVersion":"11.5.2","description":"SolWave x402 Protocol SDK for Solana: AI-powered agent-to-agent payments","directories":{"example":"examples"},"_nodeVersion":"22.18.0","dependencies":{"@solana/web3.js":"^1.98.4"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.0.0","vitest":"^2.1.0","ts-node":"^10.9.1","typescript":"^5.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/x402-sdk_0.3.0_1764231861788_0.6079000941781592","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@0xsupremedev/x402-sdk","version":"0.3.1","description":"SolWave x402 Protocol SDK for Solana: AI-powered agent-to-agent payments","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","lint":"eslint \"src/**/*.ts\"","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["solana","x402","payments","ai-agents","sdk","web3","autonomous-agents"],"author":{"name":"Supreme Dev","email":"0xsupremedev@gmail.com"},"license":"MIT","devDependencies":{"@types/node":"^22.0.0","eslint":"^8.0.0","ts-node":"^10.9.1","typescript":"^5.0.0","vitest":"^2.1.0"},"dependencies":{"@solana/web3.js":"^1.98.4"},"directories":{"example":"examples"},"type":"commonjs","_id":"@0xsupremedev/x402-sdk@0.3.1","gitHead":"f46ffc54ce9689bdc08c33f8c88afd095133d2f9","_nodeVersion":"22.18.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-juwsiv7ZkVHlG571KiRVSlRq7WTIB5sec6lDokLZBPrqDSgGLxljcGekbI6xJnL0R9BHeJaNCs33T4iOtV4BqA==","shasum":"c1eaaa2e99fa5671e184f5c86fd6e7abd75bdb5f","tarball":"https://registry.npmjs.org/@0xsupremedev/x402-sdk/-/x402-sdk-0.3.1.tgz","fileCount":32,"unpackedSize":47803,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC9fDzlYJdw7KDnAOje5hZKyRz9shZsf+X+jttcNnswoAIgdrwAAB4fqRfXMxSNONZBGo9h1HBui+sSVAGIS3hN+b0="}]},"_npmUser":{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"},"maintainers":[{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x402-sdk_0.3.1_1764232722298_0.7661156084524732"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-27T08:10:59.605Z","modified":"2025-11-27T08:38:42.683Z","0.2.0":"2025-11-27T08:10:59.917Z","0.3.0":"2025-11-27T08:24:22.006Z","0.3.1":"2025-11-27T08:38:42.496Z"},"author":{"name":"Supreme Dev","email":"0xsupremedev@gmail.com"},"license":"MIT","keywords":["solana","x402","payments","ai-agents","sdk","web3","autonomous-agents"],"description":"SolWave x402 Protocol SDK for Solana: AI-powered agent-to-agent payments","maintainers":[{"name":"0xsupremedev","email":"0xsupremedev@gmail.com"}],"readme":"# @0xsupremedev/x402-sdk\r\n\r\nSolWave x402 Protocol SDK for Solana: **AI-powered agent-to-agent payments**.\r\n\r\nThis SDK provides a simple, TypeScript-first interface for creating x402 invoices, building Solana transactions, and completing payments for AI agents, merchants, and bots.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @0xsupremedev/x402-sdk @solana/web3.js\r\n# or\r\npnpm add @0xsupremedev/x402-sdk @solana/web3.js\r\n```\r\n\r\n## Who is this for?\r\n\r\n- **AI agents** that need to initiate and settle payments on Solana.\r\n- **Merchants** who want x402-style invoices and receipts for their users.\r\n- **Bot and backend developers** integrating SolWave-style payment flows.\r\n\r\n## Quick start (Node.js)\r\n\r\n```ts\r\nimport { Keypair } from '@solana/web3.js';\r\nimport {\r\n  X402SDK,\r\n  type X402PaymentRequest,\r\n} from '@0xsupremedev/x402-sdk';\r\n\r\nconst keypair = Keypair.generate();\r\n\r\nconst sdk = new X402SDK({\r\n  rpcUrl: 'https://api.devnet.solana.com',\r\n  keypair,\r\n  apiBaseUrl: 'https://your-backend.example.com', // optional, for invoice APIs\r\n});\r\n\r\nasync function run() {\r\n  // 1) (Optional) Create an invoice via your backend\r\n  const invoice = await sdk.createInvoice({\r\n    merchantId: 'merchant-123',\r\n    amount: '1',\r\n    token: 'USDC',\r\n    metadata: { description: 'Test payment' },\r\n  });\r\n\r\n  console.log('Created invoice:', invoice);\r\n\r\n  // 2) Build a payment request for that invoice\r\n  const paymentRequest: X402PaymentRequest = {\r\n    invoiceId: invoice.id,\r\n    amount: invoice.amount,\r\n    token: invoice.token,\r\n    recipient: 'RecipientSolanaAddressHere',\r\n    nonce: invoice.nonce,\r\n    expiresAt: invoice.expiresAt,\r\n    metadata: invoice.metadata,\r\n  };\r\n\r\n  // 3) Pay the invoice with the SDK keypair\r\n  const receipt = await sdk.payInvoice(paymentRequest);\r\n  console.log('Payment receipt:', receipt);\r\n\r\n  // 4) Fetch the invoice status\r\n  const current = await sdk.getInvoiceStatus(invoice.id);\r\n  console.log('Invoice status:', current.status);\r\n}\r\n\r\nrun().catch(console.error);\r\n```\r\n\r\n## Browser usage (Phantom / Solflare / etc.)\r\n\r\n```ts\r\nimport { detectWalletAdapters, X402SDK } from '@0xsupremedev/x402-sdk';\r\n\r\nasync function initSdk() {\r\n  const wallets = detectWalletAdapters();\r\n  if (!wallets.length) {\r\n    throw new Error('No browser wallet detected');\r\n  }\r\n\r\n  // Pick the first detected wallet (e.g., Phantom) and turn it into a signer\r\n  const signer = wallets[0].createSigner();\r\n\r\n  const sdk = new X402SDK({\r\n    rpcUrl: 'https://api.devnet.solana.com',\r\n    signer,\r\n    apiBaseUrl: 'https://your-backend.example.com',\r\n  });\r\n\r\n  const invoice = await sdk.getInvoiceStatus('invoice-id');\r\n  const receipt = await sdk.payInvoice({\r\n    invoiceId: invoice.id,\r\n    amount: invoice.amount,\r\n    token: invoice.token,\r\n    recipient: invoice.merchantId, // replace with actual recipient\r\n    nonce: invoice.nonce,\r\n    expiresAt: invoice.expiresAt,\r\n  });\r\n\r\n  console.log('Paid invoice from browser wallet', receipt);\r\n}\r\n```\r\n\r\nSee `examples/browser-wallet/` for a minimal Vite-friendly starter that wires a connect button and calls `detectWalletAdapters()`.\r\n\r\n## API surface\r\n\r\n- `class X402SDK`:\r\n  - `constructor(config: SDKConfig)`\r\n    - Accepts either `keypair` (Node) or a generic `signer` (wallet adapter / browser).\r\n  - `createInvoice(params: CreateInvoiceParams): Promise<X402Invoice>`\r\n  - `getInvoiceStatus(invoiceId: string): Promise<X402Invoice>`\r\n  - `listInvoices(params?: ListInvoicesParams): Promise<X402Invoice[]>`\r\n  - `watchInvoice(invoiceId, callback, options?: WatchInvoiceOptions): Promise<() => void>`\r\n  - `buildPaymentTransaction(request: X402PaymentRequest): Promise<Transaction>`\r\n  - `payInvoice(request: X402PaymentRequest): Promise<X402PaymentReceipt>`\r\n  - `submitTransaction(tx: Transaction, options?: ConfirmOptions): Promise<string>`\r\n\r\n### Types\r\n\r\nAll protocol types are exported for you to use in your apps:\r\n\r\n- `X402Invoice`\r\n- `X402PaymentRequest`\r\n- `X402PaymentReceipt`\r\n- `CreateInvoiceParams`\r\n- `ListInvoicesParams`\r\n- `SDKConfig`\r\n- `WatchInvoiceOptions`\r\n- `RetryOptions`\r\n- `SDKLogEvent`\r\n- `X402Signer` (signer abstraction)\r\n- `BrowserWalletSigner`, `KeypairSigner`, and `detectWalletAdapters()` helper\r\n- `X402Error`\r\n\r\nAll types are fully typed with TypeScript and compiled to JavaScript in `dist/` for npm consumption.\r\n\r\n### SDKConfig fields\r\n\r\n- `rpcUrl` – Solana RPC endpoint.\r\n- `keypair` or `signer` – choose between a Node.js Keypair or any wallet adapter signer.\r\n- `apiBaseUrl` / `apiKey` – optional invoice backend + auth token.\r\n- `retry` – override default retry/backoff behavior (`maxAttempts`, `delayMs`, `backoffFactor`).\r\n- `logger(event)` – capture structured logs (helpful for observability/audits).\r\n- `errorHandler(error)` – centralized error reporting hook.\r\n\r\n## Security notes\r\n\r\n- **Key management**: never hard-code or log secret keys. For production, use a secure key management solution (HSM, KMS, or vault).\r\n- **Networks**: start on Solana devnet, then switch `rpcUrl` to mainnet only after full testing.\r\n- **Backend auth**: if you use `apiKey`, store it in environment variables and never commit it to source control.\r\n- **Wallet adapters**: always request permissions explicitly from the user and handle disconnect events.\r\n- **watchInvoice**: supply `maxDurationMs` / `maxAttempts` in `WatchInvoiceOptions` and always call the returned `stop()` handle when you no longer need updates.\r\n\r\n## Production checklist\r\n\r\n- [ ] Keys/signers loaded from secure storage (env vars, vault, HSM, or injected wallets).\r\n- [ ] Configure `logger` / `errorHandler` hooks to pipe logs into your observability stack.\r\n- [ ] Tune the `retry` strategy per environment to respect RPC rate limits.\r\n- [ ] Use `watchInvoice` safeguards (max duration/attempts) for long-lived processes.\r\n- [ ] Document wallet permission prompts and disconnection flows in your UI.\r\n\r\n## Testing\r\n\r\n- `npm test` – runs the Vitest suite (currently covering signer abstractions and transaction builders).\r\n- Browser wallet flows require manual testing:\r\n  1. `cd sdk/examples/browser-wallet`\r\n  2. `npm install && npm run dev`\r\n  3. Open the dev URL, connect Phantom/Solflare, and watch the console for receipts / retry logs.\r\n\r\n## Roadmap & feedback\r\n\r\n- Short-term roadmap:\r\n  - Wallet adapter support for browser-based integrations (Phantom, Solflare, etc.).\r\n  - Higher-level helpers for Telegram bots and agent workflows.\r\n  - More ergonomic receipt and error handling.\r\n- Feedback and feature requests:\r\n  - Please open issues or pull requests in the main GitHub repo.\r\n  - Tag SDK-related issues with `sdk` so they are easy to track.\r\n\r\n","readmeFilename":"README.md"}