{"_id":"@3mate/walrus-sponsor-sdk","_rev":"3-c896ba68494b1d2974129be09fcee473","name":"@3mate/walrus-sponsor-sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@3mate/walrus-sponsor-sdk","version":"0.1.0","keywords":["walrus","sui","blob","storage","sponsor","web3","3mate"],"author":{"name":"3mate Labs"},"license":"MIT","_id":"@3mate/walrus-sponsor-sdk@0.1.0","maintainers":[{"name":"easonc13","email":"eason.tw.chen@gmail.com"},{"name":"ruru_arcade","email":"ruru@3matelabs.com"}],"homepage":"https://github.com/3MateLabs/walrus-sponsor-sdk#readme","bugs":{"url":"https://github.com/3MateLabs/walrus-sponsor-sdk/issues"},"dist":{"shasum":"d8107fa3acc322972b1eb3d1010220345ce6e570","tarball":"https://registry.npmjs.org/@3mate/walrus-sponsor-sdk/-/walrus-sponsor-sdk-0.1.0.tgz","fileCount":7,"integrity":"sha512-SxgvZHfgDu3z8puQBjys/46yijiJH6zJ4cNSo5ADcGXpOGwUneZzmEl25zG0CBgnyIZAdVF12JeqZBcqbBec4w==","signatures":[{"sig":"MEUCIGFUrl44ERb7cDmjR//tLdfnbYhwVsd8/1EZ+kSBkor/AiEA+gFl3W3c6ACKXbjdYYLQiwn7BkqBnqEphS6h0vkbxzI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32378},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts --clean","prepublishOnly":"npm run build"},"_npmUser":{"name":"ruru_arcade","email":"ruru@3matelabs.com"},"repository":{"url":"git+https://github.com/3MateLabs/walrus-sponsor-sdk.git","type":"git"},"_npmVersion":"11.8.0","description":"Official SDK for 3mate Walrus Sponsor — Sponsored blob storage on Walrus","directories":{},"_nodeVersion":"25.5.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","typescript":"^5.3.3","@types/node":"^25.3.0"},"_npmOperationalInternal":{"tmp":"tmp/walrus-sponsor-sdk_0.1.0_1771855922849_0.16012598243126153","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@3mate/walrus-sponsor-sdk","version":"0.2.1","keywords":["walrus","sui","blob","storage","sponsor","web3","3mate","cli"],"author":{"name":"3mate Labs"},"license":"MIT","_id":"@3mate/walrus-sponsor-sdk@0.2.1","maintainers":[{"name":"easonc13","email":"eason.tw.chen@gmail.com"},{"name":"ruru_arcade","email":"ruru@3matelabs.com"}],"homepage":"https://github.com/3MateLabs/krilly-cli#readme","bugs":{"url":"https://github.com/3MateLabs/krilly-cli/issues"},"bin":{"krilly":"dist/cli.js"},"dist":{"shasum":"0b0cbd4b0d7040a27bb1851a5a34cb18c3f3d1a4","tarball":"https://registry.npmjs.org/@3mate/walrus-sponsor-sdk/-/walrus-sponsor-sdk-0.2.1.tgz","fileCount":10,"integrity":"sha512-7gIAB6CAzKjv5YrAQU8lY5bLI7KessG6kiStyNhmWYuQnTYsbeEDf9BwfTVFRkahbLFryHADu42/QaBznRe9eg==","signatures":[{"sig":"MEUCIEM3sptQA1zw9xm1a0G/y4sEux4Lo6S8k976g6lUYyiDAiEAxqLURyRGeBZ6ebj4H9QfRFb1KiLF+ksii4MdbfYbJxg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88686},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"5b21ce55aec131aab86a0391160a2d193b75c7e3","scripts":{"dev":"tsup --watch","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"easonc13","email":"eason.tw.chen@gmail.com"},"repository":{"url":"git+https://github.com/3MateLabs/krilly-cli.git","type":"git"},"_npmVersion":"10.9.4","description":"Walrus Sponsor SDK & CLI — upload, manage, and extend sponsored blobs on Walrus","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","typescript":"^5.3.3","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/walrus-sponsor-sdk_0.2.1_1773614838859_0.1772140257800381","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@3mate/walrus-sponsor-sdk","version":"0.3.0","description":"Walrus Sponsor SDK & CLI — upload, manage, and extend sponsored blobs on Walrus","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","bin":{"krilly":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"engines":{"node":">=18"},"scripts":{"build":"tsup","dev":"tsup --watch","prepublishOnly":"npm run build"},"keywords":["walrus","sui","blob","storage","sponsor","web3","3mate","cli"],"author":{"name":"3mate Labs"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/3MateLabs/krilly-cli.git"},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.0.1","typescript":"^5.3.3"},"_id":"@3mate/walrus-sponsor-sdk@0.3.0","gitHead":"296a9d8edf387371bc6e3b5228af444cf543b331","bugs":{"url":"https://github.com/3MateLabs/krilly-cli/issues"},"homepage":"https://github.com/3MateLabs/krilly-cli#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-zi4uMbejNySA04ttM+KQZXbXpl0g7urcUZ0SKbakJBDs5aWHnumJbQ2g5jLrIax8BlvbZUsJ6BWcBijPm1diRA==","shasum":"781efdac12ab55229cde725dbded64ae42b4e792","tarball":"https://registry.npmjs.org/@3mate/walrus-sponsor-sdk/-/walrus-sponsor-sdk-0.3.0.tgz","fileCount":10,"unpackedSize":94185,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCxn0DMNjHufF25Jkc3ionYrbEcqcqZd9H+TkiP16/YLQIhAOKRqJYfhE9cxlZTwM/fm+zW+EkoJahFuodgY2iolLQ0"}]},"_npmUser":{"name":"easonc13","email":"eason.tw.chen@gmail.com"},"directories":{},"maintainers":[{"name":"easonc13","email":"eason.tw.chen@gmail.com"},{"name":"ruru_arcade","email":"ruru@3matelabs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/walrus-sponsor-sdk_0.3.0_1773615803099_0.21106418169207708"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-23T14:12:02.678Z","modified":"2026-03-15T23:03:23.442Z","0.1.0":"2026-02-23T14:12:03.001Z","0.2.1":"2026-03-15T22:47:18.990Z","0.3.0":"2026-03-15T23:03:23.279Z"},"bugs":{"url":"https://github.com/3MateLabs/krilly-cli/issues"},"author":{"name":"3mate Labs"},"license":"MIT","homepage":"https://github.com/3MateLabs/krilly-cli#readme","keywords":["walrus","sui","blob","storage","sponsor","web3","3mate","cli"],"repository":{"type":"git","url":"git+https://github.com/3MateLabs/krilly-cli.git"},"description":"Walrus Sponsor SDK & CLI — upload, manage, and extend sponsored blobs on Walrus","maintainers":[{"name":"easonc13","email":"eason.tw.chen@gmail.com"},{"name":"ruru_arcade","email":"ruru@3matelabs.com"}],"readme":"# @3mate/walrus-sponsor-sdk\n\n[![npm version](https://img.shields.io/npm/v/@3mate/walrus-sponsor-sdk)](https://www.npmjs.com/package/@3mate/walrus-sponsor-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nOfficial SDK & CLI for [Walrus Sponsor Service](https://walrus-sponsor.krill.tube) — sponsored blob storage on the [Walrus](https://walrus.space) network.\n\nZero runtime dependencies. Works in Node.js 18+ and modern browsers.\n\n## Install\n\n```bash\nnpm install @3mate/walrus-sponsor-sdk\n\n# For CLI usage (global)\nnpm install -g @3mate/walrus-sponsor-sdk\n```\n\n## Quick Start\n\n### SDK (programmatic)\n\n```typescript\nimport { WalrusSponsor } from \"@3mate/walrus-sponsor-sdk\";\n\nconst client = new WalrusSponsor({\n  apiKey: \"sbk_live_...\",\n  // baseUrl defaults to https://walrus-sponsor.krill.tube\n});\n\n// Upload a file (Node.js)\nconst result = await client.upload(\"./photo.jpg\", {\n  creatorAddress: \"0x123...\",\n  epochs: 5,\n});\n\nconsole.log(\"Blob ID:\", result.blob_id);\nconsole.log(\"View:\", client.getBlobUrl(result.blob_id));\n\n// Upload a file (Browser)\nconst file = document.querySelector<HTMLInputElement>(\"#file\")!.files![0];\nconst browserResult = await client.upload(file, {\n  creatorAddress: \"0x123...\",\n  epochs: 3,\n});\n```\n\n### CLI\n\n```bash\n# Configure (API key stored in OS keychain — never plaintext on disk)\nkrilly config set-key sbk_live_abc123...\n\n# Upload\nkrilly upload ./photo.jpg --creator 0x123... --epochs 5\n\n# List blobs\nkrilly blobs --status active --pretty\n\n# Get blob details\nkrilly blob 0xabc...\n\n# Estimate cost\nkrilly cost --size 1048576 --epochs 3 --pretty\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew WalrusSponsor({\n  apiKey: string;              // Required — sbk_live_...\n  baseUrl?: string;            // Default: https://walrus-sponsor.krill.tube\n  aggregatorUrl?: string;      // Default: https://aggregator.walrus-mainnet.walrus.space\n});\n```\n\n### Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `health()` | Check if service is live | `{ status, timestamp }` |\n| `epoch()` | Get current Walrus epoch info | `{ currentEpoch, startTime, endTime }` |\n| `storageCost(size, epochs)` | Estimate WAL storage cost | `{ total_cost, storage_cost, write_cost }` |\n| `upload(file, opts)` | Upload file (sponsor pays WAL) | `{ blob_id, tx_digest, ... }` |\n| `blobs(opts?)` | List blobs (filter by status/creator) | `{ blobs[], total }` |\n| `blob(id)` | Get single blob detail | `BlobDetail` |\n| `delete(blobId, systemObjId)` | Delete blob, reclaim storage | `{ tx_digest, storage_returned }` |\n| `extend(opts)` | Extend blob storage duration | `{ new_end_epoch, tx_digest }` |\n| `fund(blobId, coinId)` | Add WAL funds to a blob | `{ tx_digest }` |\n| `register(opts)` | Advanced: client-side upload step 1 | `{ blob_object_id, tx_digest }` |\n| `certify(opts)` | Advanced: client-side upload step 2 | `{ sponsored_blob_id, tx_digest }` |\n| `getBlobUrl(blobId)` | Get aggregator download URL | `string` |\n\n### Upload Options\n\n```typescript\nclient.upload(file, {\n  creatorAddress: \"0x...\",  // Required — who owns the blob\n  epochs: 5,               // Storage duration (default: 1)\n  deletable: true,         // Allow deletion before expiry (default: true)\n  filename: \"photo.jpg\",   // Optional filename override\n  contentType: \"image/jpeg\", // Optional MIME type\n});\n```\n\nThe `file` parameter accepts:\n- **Node.js**: `string` (file path), `Buffer`, `Uint8Array`, `ReadableStream`\n- **Browser**: `File`, `Blob`\n\n## CLI Commands\n\n### Config\n\n```bash\nkrilly config set-key <api_key>        # Save API key (OS keychain)\nkrilly config set-url <url>            # Set backend URL\nkrilly config set-aggregator <url>     # Set aggregator URL\nkrilly config show                     # Show current config\n```\n\n> 🔒 API keys are stored in your OS keychain (macOS Keychain / Linux libsecret).\n> Falls back to AES-256-GCM encrypted file if keychain is unavailable.\n\n### Operations\n\n```bash\nkrilly health\nkrilly epoch\nkrilly cost --size <bytes> --epochs <n>\n\nkrilly upload <file> --creator <address> [--epochs <n>] [--deletable]\nkrilly blobs [--status <s>] [--creator <addr>] [--limit <n>] [--offset <n>]\nkrilly blob <id>\nkrilly delete <id> --system-object <id>\nkrilly extend <id> --epochs <n> --system-object <id> --payment-coin <id>\nkrilly fund <id> --coin <id>\n\nkrilly url <blob_id>\n```\n\nAdd `--pretty` to any command for formatted JSON output.\n\n## Error Handling\n\n```typescript\nimport { WalrusSponsor, WalrusSponsorError } from \"@3mate/walrus-sponsor-sdk\";\n\nconst client = new WalrusSponsor({ apiKey: \"sbk_live_...\" });\n\ntry {\n  await client.upload(\"./file.txt\", { creatorAddress: \"0x...\" });\n} catch (err) {\n  if (err instanceof WalrusSponsorError) {\n    console.error(`API Error [${err.status}]: ${err.message}`);\n    // err.code — e.g. \"INSUFFICIENT_BALANCE\", \"RATE_LIMIT_EXCEEDED\"\n  }\n}\n```\n\n## Security\n\n- API keys are **never stored in plaintext** on disk\n- macOS: stored in Keychain (`security` CLI)\n- Linux: stored in GNOME Keyring / KDE Wallet (`secret-tool`)\n- Fallback: AES-256-GCM encrypted file at `~/.krilly/.vault`\n- Non-secret config (`baseUrl`) stored in `~/.krilly/config.json`\n\n## License\n\nMIT — [3mate Labs](https://github.com/3MateLabs)\n\n## AI Agent Integration\n\nKrilly is designed to be agent-friendly. Give your AI agent decentralized storage in one line:\n\n```typescript\nimport { WalrusSponsor } from \"krilly\";\n\nconst walrus = new WalrusSponsor({\n  apiKey: process.env.WALRUS_API_KEY, // set in agent environment\n});\n\n// Upload agent-generated content\nconst result = await walrus.upload(\n  { data: Buffer.from(output), filename: \"report.json\", contentType: \"application/json\" },\n  { creatorAddress: \"0x...\", epochs: 5 }\n);\n\n// Permanent, decentralized URL — no auth needed to read\nconst url = walrus.getBlobUrl(result.blob_id);\n```\n\n### For Agent Frameworks\n\nEach SDK method maps 1:1 to a tool/function call:\n\n| Tool | Method | Description |\n|------|--------|-------------|\n| `walrus_upload` | `upload(file, opts)` | Store file on Walrus |\n| `walrus_list` | `blobs(opts?)` | List stored blobs |\n| `walrus_get` | `blob(id)` | Get blob metadata |\n| `walrus_cost` | `estimateCost(size, epochs)` | Estimate cost |\n| `walrus_delete` | `delete(id, sysObj)` | Delete blob |\n| `walrus_extend` | `extend(opts)` | Extend storage |\n| `walrus_url` | `getBlobUrl(id)` | Get download URL |\n\nWorks with LangChain, CrewAI, AutoGPT, OpenClaw, or any framework that supports npm packages.\n\n### CLI for Shell-Based Agents\n\n```bash\nexport WALRUS_API_KEY=sbk_live_...\nkrilly config set-key $WALRUS_API_KEY\nkrilly upload ./data.json --creator 0x... --epochs 5\nkrilly blobs --pretty\n```\n\nSee full docs: https://walrus-sponsor.krill.tube/docs/ai-agents\n","readmeFilename":"README.md"}