{"_id":"@0xopenseeddev/sdk","name":"@0xopenseeddev/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@0xopenseeddev/sdk","version":"0.1.0","description":"Programmatic SDK for spawning and managing OpenSeed seller nodes","type":"module","main":"src/index.js","exports":{".":"./src/index.js","./seller":"./src/seller.js","./network":"./src/network.js"},"scripts":{"build":"echo 'sdk has no build step'"},"keywords":["openseed","sdk","p2p","ai"],"license":"ISC","_id":"@0xopenseeddev/sdk@0.1.0","gitHead":"08c07b286b68badfc9c21539c68d01db3a795b60","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-YPPJNxPCN3I9c+l2fH8STMcxuNaS3r1prRswCet221UQOT06z+zN2+x95D9Uo2xFMSS8urtBYkcaLCQh/cqAtg==","shasum":"48921acbdc202b10e0648c222877051e2c45d966","tarball":"https://registry.npmjs.org/@0xopenseeddev/sdk/-/sdk-0.1.0.tgz","fileCount":6,"unpackedSize":20254,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDKMaHHacMauX02DuyTNVQmt4E2AzBh0dC3+rm9KtUvAQIgH1EYjGKzcaIkQDxDSazLmLiFxdBjI/woqJ2oh3ihrxg="}]},"_npmUser":{"name":"0xopenseeddev","email":"openseed.gg@gmail.com"},"directories":{},"maintainers":[{"name":"0xopenseeddev","email":"openseed.gg@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1778758598750_0.863080693207396"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T11:36:38.605Z","0.1.0":"2026-05-14T11:36:38.892Z","modified":"2026-05-14T11:36:39.106Z"},"maintainers":[{"name":"0xopenseeddev","email":"openseed.gg@gmail.com"}],"description":"Programmatic SDK for spawning and managing OpenSeed seller nodes","keywords":["openseed","sdk","p2p","ai"],"license":"ISC","readme":"# @0xopenseeddev/sdk\n\nProgrammatic SDK for the **OpenSeed** network.  \nSpin up seller nodes, define AI offerings, and orchestrate a local peer network — all from JavaScript.\n\n---\n\n## Installation\n\nThe SDK is a workspace package and is available automatically within the monorepo.  \nImport directly from source:\n\n```js\nimport { Network, SellerNode, Offering } from './packages/sdk/src/index.js';\n```\n\nOr, if published externally:\n\n```sh\nnpm install @0xopenseeddev/sdk\n```\n\n---\n\n## Quick Start\n\n```js\nimport { Network, Offering } from '@0xopenseeddev/sdk';\n\nconst net = new Network({\n  apiKey:      process.env.OPENROUTER_API_KEY,\n  registryUrl: 'http://localhost:9000'\n});\n\nnet\n  .addSeller({\n    port:   8401,\n    peerId: 'my-node-001',\n    offerings: [\n      new Offering('inference')\n        .name('Llama 3 8B')\n        .description('Fast open-source model for everyday tasks.')\n        .services(['llama-3-8b'])\n        .pricing({ inputUsdPerMillion: 0.05, outputUsdPerMillion: 0.05 })\n        .upstreamModel('meta-llama/llama-3-8b-instruct:free')\n    ]\n  });\n\nawait net.start();\n// SIGINT / SIGTERM are handled automatically — Ctrl+C shuts everything down cleanly.\n```\n\n---\n\n## API Reference\n\n### `Offering`\n\nFluent builder for a single capability advertised by a seller node.\n\n```js\nnew Offering(capability)\n```\n\n| Argument | Type | Description |\n|---|---|---|\n| `capability` | `'inference' \\| 'agent' \\| 'tool'` | Capability type |\n\n**Chain methods** (all return `this`):\n\n| Method | Argument | Description |\n|---|---|---|\n| `.name(str)` | `string` | Human-readable offering name |\n| `.description(str)` | `string` | Short description shown to buyers |\n| `.services(ids)` | `string[]` | Model/service IDs buyers request (e.g. `['gpt-4o-mini']`) |\n| `.pricing(p)` | `object` | Pricing in USD per 1M tokens (see below) |\n| `.upstreamModel(str)` | `string` | Model name forwarded upstream (e.g. `'openai/gpt-4o-mini'`) |\n\n**Pricing object:**\n\n```js\n{\n  inputUsdPerMillion:       0.15,  // required\n  cachedInputUsdPerMillion: 0.075, // optional, defaults to inputUsdPerMillion\n  outputUsdPerMillion:      0.60   // required\n}\n```\n\n> `.toJSON()` validates all required fields and throws if anything is missing.\n\n**Example:**\n\n```js\nnew Offering('agent')\n  .name('Code Master')\n  .description('Best-in-class coding agent.')\n  .services(['claude-3-5-sonnet'])\n  .pricing({ inputUsdPerMillion: 3.00, cachedInputUsdPerMillion: 1.50, outputUsdPerMillion: 15.00 })\n  .upstreamModel('anthropic/claude-3-5-sonnet')\n```\n\n---\n\n### `SellerNode`\n\nWraps a forked seller process. Extends `EventEmitter`.\n\n```js\nnew SellerNode(opts)\n```\n\n**Options:**\n\n| Option | Type | Required | Description |\n|---|---|---|---|\n| `peerId` | `string` | ✅ | Unique peer identifier |\n| `port` | `number` | ✅ | HTTP port to listen on |\n| `offerings` | `Offering[]` | ✅ | At least one `Offering` instance |\n| `endpoint` | `string` | — | Public URL buyers connect to (default: `http://localhost:<port>`) |\n| `merchantAddress` | `string` | — | On-chain address for payment receipts |\n| `registryUrl` | `string` | — | Registry base URL (default: `http://localhost:9000`) |\n| `apiKey` | `string` | — | Upstream AI provider key |\n| `upstreamBaseUrl` | `string` | — | Upstream base URL (default: OpenRouter) |\n| `sellerPrivateKey` | `string` | — | Seller private key for on-chain settlement |\n| `contractAddress` | `string` | — | AntseedDeposits contract address |\n| `chainName` | `string` | — | `'base'` \\| `'base-sepolia'` \\| `'localhost'` |\n| `rpcUrl` | `string` | — | RPC endpoint |\n| `sellerPath` | `string` | — | Override path to seller entry point |\n| `env` | `object` | — | Extra env vars passed to the child process |\n\n**Methods:**\n\n```js\nawait node.start()  // fork the process; resolves once forked\nawait node.stop()   // send SIGTERM and wait for exit\nnode.info()         // { peerId, port, endpoint, running, offerings[] }\n```\n\n**Events:**\n\n```js\nnode.on('started', ({ peerId, port }) => { /* process is up and listening */ })\nnode.on('error',   (err)             => { /* fork failed */ })\nnode.on('exit',    ({ peerId, code, signal }) => { /* process exited */ })\n```\n\n**Example:**\n\n```js\nimport { SellerNode, Offering } from '@0xopenseeddev/sdk';\n\nconst node = new SellerNode({\n  peerId: 'my-node-001',\n  port:   8401,\n  apiKey: process.env.OPENROUTER_API_KEY,\n  offerings: [\n    new Offering('inference')\n      .name('GPT-4o Mini')\n      .services(['gpt-4o-mini'])\n      .pricing({ inputUsdPerMillion: 0.15, outputUsdPerMillion: 0.60 })\n      .upstreamModel('openai/gpt-4o-mini')\n  ]\n});\n\nnode.on('started', () => console.log('Node is ready!'));\nnode.on('exit',    ({ code }) => console.log('Exited with code', code));\n\nawait node.start();\n\n// Later:\nawait node.stop();\n```\n\n---\n\n### `Network`\n\nOrchestrates multiple `SellerNode` instances with shared defaults.  \nExtends `EventEmitter`.\n\n```js\nnew Network(defaults?)\n```\n\n**Defaults (applied to every node added via `.addSeller()`):**\n\n| Option | Type | Description |\n|---|---|---|\n| `apiKey` | `string` | Upstream AI provider key |\n| `upstreamBaseUrl` | `string` | Upstream base URL |\n| `registryUrl` | `string` | Registry base URL |\n| `merchantAddress` | `string` | Shared merchant address |\n| `env` | `object` | Extra env vars (merged with per-node env) |\n\n**Methods:**\n\n```js\nnet.addSeller(opts)  // same opts as SellerNode; returns Network (chainable)\nawait net.start()    // start all nodes concurrently; hooks SIGINT/SIGTERM\nawait net.stop()     // stop all running nodes concurrently\nnet.list()           // array of node.info() for each node\nnet.size             // number of nodes\n```\n\n**Events:**\n\n```js\nnet.on('node:started', ({ peerId, port }) => { })\nnet.on('node:error',   ({ peerId, err })  => { })\nnet.on('node:exit',    ({ peerId, code }) => { })\n```\n\n**Example — multi-node simulation:**\n\n```js\nimport { Network, Offering } from '@0xopenseeddev/sdk';\n\nconst net = new Network({\n  apiKey:      process.env.OPENROUTER_KEY,\n  registryUrl: 'http://localhost:9000',\n  merchantAddress: '0xYourAddress'\n});\n\nnet\n  .addSeller({\n    port:   8401,\n    peerId: 'peer-llama-001',\n    offerings: [\n      new Offering('inference')\n        .name('Llama 3 8B')\n        .services(['llama-3-8b'])\n        .pricing({ inputUsdPerMillion: 0.05, outputUsdPerMillion: 0.05 })\n        .upstreamModel('meta-llama/llama-3-8b-instruct:free')\n    ]\n  })\n  .addSeller({\n    port:   8402,\n    peerId: 'peer-gemini-002',\n    offerings: [\n      new Offering('inference')\n        .name('Gemini 2.5 Flash')\n        .services(['gemini-2.5-flash'])\n        .pricing({ inputUsdPerMillion: 0.27, outputUsdPerMillion: 0.27 })\n        .upstreamModel('google/gemini-2.5-flash')\n    ]\n  });\n\nawait net.start();\n// Ctrl+C → graceful shutdown of all nodes\n```\n\n---\n\n## Environment Variables\n\nAll environment variables from the parent process are inherited by child nodes.  \nThe SDK additionally injects the following:\n\n| Variable | Source |\n|---|---|\n| `PEER_ID` | `opts.peerId` |\n| `SELLER_PORT` | `opts.port` |\n| `SELLER_ENDPOINT` | `opts.endpoint` |\n| `REGISTRY_URL` | `opts.registryUrl` |\n| `OFFERINGS` | serialised JSON of offerings |\n| `MERCHANT_ADDRESS` | `opts.merchantAddress` |\n| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | `opts.apiKey` |\n| `UPSTREAM_BASE_URL` | `opts.upstreamBaseUrl` |\n| `SELLER_PRIVATE_KEY` | `opts.sellerPrivateKey` |\n| `CONTRACT_ADDRESS` | `opts.contractAddress` |\n| `CHAIN_NAME` | `opts.chainName` |\n| `RPC_URL` | `opts.rpcUrl` |\n\n---\n\n## Package Layout\n\n```\npackages/sdk/\n├── src/\n│   ├── index.js      ← barrel export\n│   ├── offering.js   ← Offering builder\n│   ├── seller.js     ← SellerNode (fork wrapper)\n│   └── network.js    ← Network (multi-node orchestrator)\n└── package.json\n```\n\n---\n\n## See Also\n\n- [`simulate.js`](../../simulate.js) — live example using the SDK to boot a 3-peer local network\n- [`packages/seller`](../seller) — the seller node implementation the SDK forks\n- [`packages/cli`](../cli) — CLI that also uses the seller node programmatically\n","readmeFilename":"README.md","_rev":"1-52e39cc10cf69b2c8b89e22ab4b95e64"}