{"_id":"@atomic402/sui-sdk","_rev":"3-b1f37cd84157d7261806d3583edee3de","name":"@atomic402/sui-sdk","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@atomic402/sui-sdk","version":"0.0.1","keywords":["sui","x402","payment","blockchain","web3","ptb","programmable-transaction","atomic-payment","sui-sdk","payment-required"],"author":{"name":"fac3m4n"},"license":"MIT","_id":"@atomic402/sui-sdk@0.0.1","maintainers":[{"name":"ak_bunny47","email":"akerimberdi@gmail.com"}],"homepage":"https://github.com/fac3m4n/atomic402#readme","bugs":{"url":"https://github.com/fac3m4n/atomic402/issues"},"dist":{"shasum":"06dca1a89c569e91383ebff536538e4cbe67bd29","tarball":"https://registry.npmjs.org/@atomic402/sui-sdk/-/sui-sdk-0.0.1.tgz","fileCount":19,"integrity":"sha512-fcWUfKd3GSOuFSx7rHHDva/CLNUCxzS2Ywf3ENIbuyja9+o7orev90RQzzl0iYP5LfGlkypVui3DOAJUZ6d48w==","signatures":[{"sig":"MEYCIQDlWLE1cPf8qX6f5VY728QSL99Au9zqdJ+abJSdeK5hAAIhANgbhlKglpZ6O/+8rgVwz4WziUvIm3C4GxNflGKsBAZe","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49373},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/client.d.ts","import":"./dist/client.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"}},"gitHead":"94e78db05ed19064884870057fed7c2099059fbd","private":false,"scripts":{"lint":"eslint . --max-warnings 0","build":"tsc -p tsconfig.build.json","check-types":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"ak_bunny47","email":"akerimberdi@gmail.com"},"repository":{"url":"git+https://github.com/fac3m4n/atomic402.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.5.1","description":"TypeScript SDK for x402 (Payment Required) protocol on Sui blockchain with atomic payment + access grant","directories":{},"_nodeVersion":"24.6.0","dependencies":{"@mysten/sui":"^1.45.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.39.1","typescript":"5.9.2","@types/node":"^22.15.3","@repo/eslint-config":"*","@repo/typescript-config":"*"},"peerDependencies":{"@mysten/sui":"^1.45.0"},"_npmOperationalInternal":{"tmp":"tmp/sui-sdk_0.0.1_1763232371975_0.6055616042707559","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@atomic402/sui-sdk","version":"0.0.2","keywords":["sui","x402","payment","blockchain","web3","ptb","programmable-transaction","atomic-payment","sui-sdk","payment-required"],"author":{"name":"fac3m4n"},"license":"MIT","_id":"@atomic402/sui-sdk@0.0.2","maintainers":[{"name":"ak_bunny47","email":"akerimberdi@gmail.com"}],"homepage":"https://github.com/fac3m4n/atomic402#readme","bugs":{"url":"https://github.com/fac3m4n/atomic402/issues"},"dist":{"shasum":"5f7250e852e0958861ed733927687ca60a65bb86","tarball":"https://registry.npmjs.org/@atomic402/sui-sdk/-/sui-sdk-0.0.2.tgz","fileCount":19,"integrity":"sha512-IjA5vNfC5SugyMG0TsUruqSuBxuRJETbvt7ygHw3gjkZvo1YNQ7TzDsCXWdlwWTTIT53uucXyjyAlZ5zXeDjrQ==","signatures":[{"sig":"MEUCIQDlocGJefip1MlX4piWs2Hu7VRecA44kJpRZf15+yCmzgIgM4ebn54qvhofI72Xu8rE5WzxiYaxRmkVDemhiKsVsUo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49373},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/client.d.ts","import":"./dist/client.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"}},"gitHead":"94e78db05ed19064884870057fed7c2099059fbd","private":false,"scripts":{"lint":"eslint . --max-warnings 0","build":"tsc -p tsconfig.build.json","check-types":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"ak_bunny47","email":"akerimberdi@gmail.com"},"repository":{"url":"git+https://github.com/fac3m4n/atomic402.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.5.1","description":"TypeScript SDK for x402 (Payment Required) protocol on Sui blockchain with atomic payment + access grant","directories":{},"_nodeVersion":"24.6.0","dependencies":{"@mysten/sui":"^1.45.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.39.1","typescript":"5.9.2","@types/node":"^22.15.3","@repo/eslint-config":"*","@repo/typescript-config":"*"},"peerDependencies":{"@mysten/sui":"^1.45.0"},"_npmOperationalInternal":{"tmp":"tmp/sui-sdk_0.0.2_1763232538272_0.8280672228954133","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-11-15T18:46:11.788Z","modified":"2026-07-26T07:21:33.327Z","0.0.1":"2025-11-15T18:46:12.236Z","0.0.2":"2025-11-15T18:48:58.466Z"},"bugs":{"url":"https://github.com/fac3m4n/atomic402/issues"},"author":{"name":"fac3m4n"},"license":"MIT","homepage":"https://github.com/fac3m4n/atomic402#readme","keywords":["sui","x402","payment","blockchain","web3","ptb","programmable-transaction","atomic-payment","sui-sdk","payment-required"],"repository":{"url":"git+https://github.com/fac3m4n/atomic402.git","type":"git","directory":"packages/sdk"},"description":"TypeScript SDK for x402 (Payment Required) protocol on Sui blockchain with atomic payment + access grant","maintainers":[{"email":"akerimberdi@gmail.com","name":"kevo_0"}],"readme":"# @atomic402/sui-sdk\n\nTypeScript SDK for implementing x402 (Payment Required) protocol on Sui blockchain.\n\n## Features\n\n- 🏗️ **Server SDK**: Build PTBs and generate x402 responses\n- 💳 **Client SDK**: Sign transactions and verify access\n- ⚡ **Atomic Execution**: Payment and action in one transaction\n- 🎯 **Type-Safe**: Full TypeScript support\n- 🤖 **AI-Ready**: Perfect for autonomous agents\n\n## Installation\n\n```bash\nnpm install @atomic402/sui-sdk @mysten/sui\n# or\nbun add @atomic402/sui-sdk @mysten/sui\n```\n\n## Quick Start\n\n### Server-Side\n\n```typescript\nimport { createX402Server } from \"@atomic402/sui-sdk\";\nimport { SuiClient } from \"@mysten/sui/client\";\nimport { Ed25519Keypair } from \"@mysten/sui/keypairs/ed25519\";\n\n// Initialize\nconst client = new SuiClient({ url: \"https://fullnode.testnet.sui.io:443\" });\nconst sponsorKeypair = Ed25519Keypair.fromSecretKey(/* ... */);\n\nconst x402Server = createX402Server({\n  suiClient: client,\n  packageId: \"0xYOUR_PACKAGE_ID\",\n  sponsorKeypair, // Optional: for gasless transactions\n});\n\n// Generate x402 response\nconst response = await x402Server.generateX402Response(\n  {\n    id: \"content_1\",\n    title: \"Premium Article\",\n    price: \"100000000\", // 0.1 SUI in MIST\n    creator: \"0xCREATOR_ADDRESS\",\n    // ... other fields\n  },\n  buyerAddress\n);\n\n// Returns:\n// {\n//   statusCode: 402,\n//   message: 'Payment Required',\n//   paymentRequired: {\n//     amount: '100000000',\n//     recipient: '0xCREATOR_ADDRESS',\n//     transactionBytes: 'base64_encoded_ptb',\n//     description: 'Purchase access to: Premium Article'\n//   }\n// }\n\n// Execute signed transaction\nconst result = await x402Server.sponsorAndExecute(\n  transactionBytes,\n  clientSignature,\n  clientPublicKey\n);\n\nconsole.log(\"Transaction:\", result.digest);\n```\n\n### Client-Side\n\n```typescript\nimport { createX402Client } from \"@atomic402/sui-sdk\";\nimport { SuiClient } from \"@mysten/sui/client\";\n\n// Initialize\nconst client = new SuiClient({ url: \"https://fullnode.testnet.sui.io:443\" });\n\nconst x402Client = createX402Client({\n  suiClient: client,\n  packageId: \"0xYOUR_PACKAGE_ID\",\n});\n\n// Handle x402 flow\nconst digest = await x402Client.handleX402Flow(\n  \"https://api.example.com\",\n  \"content_1\",\n  keypair\n);\n\nconsole.log(\"Purchase complete:\", digest);\n\n// Check access\nconst hasAccess = await x402Client.checkAccess(userAddress, \"content_1\");\n\n// Get all receipts\nconst receipts = await x402Client.getAccessReceipts(userAddress);\n```\n\n### Browser/Wallet Integration\n\n```typescript\nimport { useSignTransaction, useCurrentAccount } from '@mysten/dapp-kit';\n\nfunction PurchaseButton({ contentId }) {\n  const account = useCurrentAccount();\n  const { mutateAsync: signTransaction } = useSignTransaction();\n\n  const handlePurchase = async () => {\n    // 1. Get x402 response\n    const response = await fetch(`/api/content/${contentId}?address=${account.address}`);\n    const x402 = await response.json();\n\n    // 2. Sign transaction\n    const txBytes = Buffer.from(x402.paymentRequired.transactionBytes, 'base64');\n    const { signature } = await signTransaction({ transaction: txBytes });\n\n    // 3. Submit to server\n    const result = await fetch(`/api/content/${contentId}/execute`, {\n      method: 'POST',\n      body: JSON.stringify({\n        transactionBytes: x402.paymentRequired.transactionBytes,\n        signature,\n        publicKey: account.publicKey,\n      }),\n    });\n\n    console.log('Success!', await result.json());\n  };\n\n  return <button onClick={handlePurchase}>Purchase</button>;\n}\n```\n\n## API Reference\n\n### Server SDK\n\n#### `createX402Server(config)`\n\nCreates a new x402 server instance.\n\n**Parameters:**\n\n```typescript\n{\n  suiClient: SuiClient;        // Sui client instance\n  packageId: string;           // Deployed Move package ID\n  sponsorKeypair?: Ed25519Keypair;  // Optional: for gasless txs\n  contentModule?: string;      // Default: 'content_access'\n}\n```\n\n#### `generateX402Response(content, buyerAddress)`\n\nGenerates an HTTP 402 response with PTB.\n\n**Returns:** `Promise<X402Response>`\n\n#### `sponsorAndExecute(txBytes, signature, publicKey)`\n\nSponsors and executes a client-signed transaction.\n\n**Returns:** `Promise<TransactionResult>`\n\n#### `createContent(title, description, price, url, creatorKeypair)`\n\nCreates new premium content on-chain.\n\n**Returns:** `Promise<string>` (content object ID)\n\n#### `getContentDetails(contentObjectId)`\n\nFetches content metadata from chain.\n\n**Returns:** `Promise<ContentMetadata | null>`\n\n#### `hasAccess(ownerAddress, contentId)`\n\nChecks if an address owns access to content.\n\n**Returns:** `Promise<boolean>`\n\n### Client SDK\n\n#### `createX402Client(config)`\n\nCreates a new x402 client instance.\n\n**Parameters:**\n\n```typescript\n{\n  suiClient: SuiClient;\n  packageId: string;\n  moduleName?: string;  // Default: 'content_access'\n}\n```\n\n#### `parseX402Response(response)`\n\nParses and validates an x402 response.\n\n**Returns:** Payment details object\n\n#### `signWithKeypair(transactionBytes, keypair)`\n\nSigns a transaction using a keypair (for automation).\n\n**Returns:** `Promise<SignedTransactionRequest>`\n\n#### `signWithWallet(transactionBytes, wallet)`\n\nSigns a transaction using a browser wallet.\n\n**Returns:** `Promise<SignedTransactionRequest>`\n\n#### `submitSignedTransaction(serverUrl, contentId, signedTx)`\n\nSubmits signed transaction to server.\n\n**Returns:** `Promise<{ digest: string; status: string }>`\n\n#### `handleX402Flow(serverUrl, contentId, keypair)`\n\nComplete automated flow for AI agents/scripts.\n\n**Returns:** `Promise<string>` (transaction digest)\n\n#### `checkAccess(userAddress, contentId)`\n\nChecks if user has access to content.\n\n**Returns:** `Promise<boolean>`\n\n#### `getAccessReceipts(userAddress)`\n\nGets all access receipts owned by address.\n\n**Returns:** `Promise<AccessReceiptData[]>`\n\n#### `waitForTransaction(digest, timeoutMs?)`\n\nWaits for transaction confirmation.\n\n**Returns:** `Promise<boolean>`\n\n## Types\n\n### X402Response\n\n```typescript\n{\n  statusCode: 402;\n  message: string;\n  paymentRequired: {\n    amount: string;\n    recipient: string;\n    transactionBytes: string;\n    description: string;\n  }\n}\n```\n\n### ContentMetadata\n\n```typescript\n{\n  id: string;\n  title: string;\n  description: string;\n  price: string;\n  contentUrl: string;\n  creator: string;\n}\n```\n\n### AccessReceiptData\n\n```typescript\n{\n  id: string;\n  contentId: string;\n  contentTitle: string;\n  pricePaid: string;\n  purchaser: string;\n  timestamp: string;\n}\n```\n\n## Advanced Usage\n\n### Custom PTBs\n\n```typescript\nconst tx = await x402Server.buildPurchaseTransaction({\n  contentObjectId: \"0xCONTENT_ID\",\n  price: \"100000000\",\n  creator: \"0xCREATOR\",\n  buyerAddress: \"0xBUYER\",\n});\n\n// Add custom logic\ntx.moveCall({\n  target: `${packageId}::custom::extra_logic`,\n  arguments: [\n    /* ... */\n  ],\n});\n\n// Execute\nconst txBytes = await tx.build({ client });\n```\n\n### Error Handling\n\n```typescript\ntry {\n  const result = await x402Server.sponsorAndExecute(txBytes, sig, pubKey);\n  if (result.status === \"failure\") {\n    console.error(\"Transaction failed:\", result.effects);\n  }\n} catch (error) {\n  if (error.message.includes(\"Insufficient gas\")) {\n    // Handle gas error\n  } else if (error.message.includes(\"Insufficient payment\")) {\n    // Handle payment error\n  }\n}\n```\n\n### Gasless Transactions\n\nTo enable gasless transactions for better UX:\n\n```typescript\nconst sponsorKeypair = Ed25519Keypair.fromSecretKey(sponsorPrivateKey);\n\nconst x402Server = createX402Server({\n  suiClient: client,\n  packageId: \"0xPACKAGE_ID\",\n  sponsorKeypair, // Server pays gas!\n});\n```\n\nUsers sign the transaction, but the server pays the gas fees.\n\n## Best Practices\n\n1. **Validate prices**: Always verify payment amounts match expected prices\n2. **Error handling**: Implement comprehensive error handling\n3. **Rate limiting**: Add rate limits to prevent abuse\n4. **Signature verification**: Never trust client-provided data\n5. **Gas budgets**: Set appropriate gas budgets for transactions\n6. **Timeouts**: Implement timeouts for long-running operations\n\n## Security Considerations\n\n- Store private keys securely (use environment variables, key management systems)\n- Validate all user inputs\n- Implement proper access control\n- Use HTTPS in production\n- Monitor for unusual activity\n- Keep dependencies updated\n\n## Examples\n\nSee the `apps/` directory for complete examples:\n\n- `apps/server`: Express/Hono API server\n- `apps/web`: Next.js frontend with wallet integration\n\n## Testing\n\n```typescript\nimport { describe, test, expect } from \"bun:test\";\n\ndescribe(\"x402 SDK\", () => {\n  test(\"generates valid x402 response\", async () => {\n    const response = await x402Server.generateX402Response(content, buyer);\n    expect(response.statusCode).toBe(402);\n    expect(response.paymentRequired.transactionBytes).toBeTruthy();\n  });\n});\n```\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## License\n\nMIT\n\n## Support\n\n- [Documentation](../../README.md)\n- [Issues](https://github.com/yourorg/x402-sui/issues)\n- [Sui Discord](https://discord.gg/sui)\n\n## Changelog\n\n### v0.1.0 (Initial Release)\n\n- Server SDK with PTB construction\n- Client SDK with transaction signing\n- x402 response generation\n- Access verification\n- Type definitions\n","readmeFilename":"README.md"}