{"_id":"@aivo-x402/solana","_rev":"2-75b5edbe7e8d165463f71d23005292b1","name":"@aivo-x402/solana","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@aivo-x402/solana","version":"1.0.0","license":"MIT","_id":"@aivo-x402/solana@1.0.0","maintainers":[{"name":"aivo-sh","email":"founder@aivo.sh"}],"homepage":"https://github.com/aivo-sh/x402-solana#readme","bugs":{"url":"https://github.com/aivo-sh/x402-solana/issues"},"dist":{"shasum":"2e05843e70553b625b348ac3a36b67ffe7572405","tarball":"https://registry.npmjs.org/@aivo-x402/solana/-/solana-1.0.0.tgz","fileCount":20,"integrity":"sha512-h0iY0NTk/ZVFRMnaxjUbXdYWrSmhDbgFkHNrrAVaZXbEaWqy4V00WkocMTM3zg2ZVk0dhjueeeLSIEvwoTkREw==","signatures":[{"sig":"MEUCIQCkRfELQ1o4u3CRfHVQ5/eoW+VoUG8yxseYWZm1yFWCsgIgNW68VUW5+nl5kQ9fuWyJcMB/qPBXowzYp2/RFHLBSQE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40326},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"46b105c37f114dc9f650b1b49ff694502c89d94e","scripts":{"lint":"biome check src/","test":"vitest run","build":"tsc -p tsconfig.json","check":"npm run typecheck && npm run lint && npm test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"aivo-sh","email":"founder@aivo.sh"},"repository":{"url":"git+https://github.com/aivo-sh/x402-solana.git","type":"git"},"_npmVersion":"10.9.0","description":"AIVO Solana layer on top of the official x402 v2 protocol — auto-DID wallet + self-hosted facilitator with x402.org fallback. Re-exports @x402/* (core, svm, hono, fetch, extensions).","directories":{},"_nodeVersion":"22.12.0","dependencies":{"@x402/svm":"^2.14.0","tweetnacl":"^1.0.3","@x402/core":"^2.14.0","@x402/hono":"^2.14.0","@x402/fetch":"^2.14.0","@solana/web3.js":"^1.95.0","@x402/extensions":"^2.14.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"npm@10.9.0","devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.2","@types/node":"^22.10.0","@biomejs/biome":"^1.9.0"},"_npmOperationalInternal":{"tmp":"tmp/solana_1.0.0_1780349565929_0.11507724487131155","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aivo-x402/solana","version":"1.0.2","description":"AIVO Solana layer on top of the official x402 v2 protocol — auto-DID wallet + self-hosted facilitator with x402.org fallback. Re-exports @x402/* (core, svm, hono, fetch, extensions).","license":"MIT","type":"module","engines":{"node":">=22.12.0"},"packageManager":"npm@10.9.0","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","typecheck":"tsc --noEmit","lint":"biome check src/","check":"npm run typecheck && npm run lint && npm test"},"dependencies":{"@x402/core":"^2.14.0","@x402/svm":"^2.14.0","@x402/hono":"^2.14.0","@x402/fetch":"^2.14.0","@x402/extensions":"^2.14.0","@solana/web3.js":"^1.95.0","tweetnacl":"^1.0.3"},"devDependencies":{"@biomejs/biome":"^1.9.0","@types/node":"^22.10.0","typescript":"^5.7.2","vitest":"^2.1.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/aivo-sh/x402-solana.git"},"homepage":"https://github.com/aivo-sh/x402-solana#readme","bugs":{"url":"https://github.com/aivo-sh/x402-solana/issues"},"_id":"@aivo-x402/solana@1.0.2","gitHead":"46b105c37f114dc9f650b1b49ff694502c89d94e","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-3qCtJSgGMbVmMnwlfg9cfGTUThRoVNGs0AZqOD+U1TeVOmGZz/lx3/gVej6n9yIgvq2OtEyyVvOVMuTFX3UtMg==","shasum":"057138fc779a4f74b65420e5347d1169a73393a2","tarball":"https://registry.npmjs.org/@aivo-x402/solana/-/solana-1.0.2.tgz","fileCount":20,"unpackedSize":40326,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHSMuTvZsmsmRg330tXBwdy818YxmMRto2zfVpavgWTyAiAS468xWvP0JbG/TY6Rb8LsXRytxn/A4OeERXHXxg3SLA=="}]},"_npmUser":{"name":"aivo-sh","email":"founder@aivo.sh"},"directories":{},"maintainers":[{"name":"aivo-sh","email":"founder@aivo.sh"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/solana_1.0.2_1780369422098_0.5470231681061712"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-01T21:32:45.785Z","modified":"2026-06-02T03:03:42.363Z","1.0.0":"2026-06-01T21:32:46.071Z","1.0.2":"2026-06-02T03:03:42.227Z"},"bugs":{"url":"https://github.com/aivo-sh/x402-solana/issues"},"license":"MIT","homepage":"https://github.com/aivo-sh/x402-solana#readme","repository":{"type":"git","url":"git+https://github.com/aivo-sh/x402-solana.git"},"description":"AIVO Solana layer on top of the official x402 v2 protocol — auto-DID wallet + self-hosted facilitator with x402.org fallback. Re-exports @x402/* (core, svm, hono, fetch, extensions).","maintainers":[{"name":"aivo-sh","email":"founder@aivo.sh"}],"readme":"<div align=\"center\">\n\n# `@aivo-x402/solana`\n\n**AIVO Solana layer on top of the official [x402 v2 protocol](https://github.com/coinbase/x402).**\n\nOne package, three jobs:\n\n1. 🔁 **Re-exports** the official `@x402/*` packages (`core`, `svm`, `hono`, `fetch`, `extensions`) so you import one name.\n2. 🪪 **Auto-DID wallet flow** — `did:sol:<pubkey>` per W3C DID spec. No signup, no API key.\n3. 🌐 **Self-hosted facilitator with `x402.org` fallback** — try self-host, fall back if it dies.\n\nBuilt for the **AIVO 3-repo stack**: this package is the shared protocol layer between [aivo-swarm](https://github.com/aivo-sh/aivo-swarm) (server) and [rover](https://github.com/aivo-sh/rover) (client). See [`AGENTS.md`](../AGENTS.md) v1.2.2 for the full spec.\n\n<br>\n\n[![npm version](https://img.shields.io/npm/v/@aivo-x402/solana.svg)](https://www.npmjs.com/package/@aivo-x402/solana)\n[![npm downloads](https://img.shields.io/npm/dm/@aivo-x402/solana.svg)](https://www.npmjs.com/package/@aivo-x402/solana)\n[![CI](https://img.shields.io/github/actions/workflow/status/aivo-sh/x402-solana/release.yml?branch=main&label=ci)](https://github.com/aivo-sh/x402-solana/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)\n[![x402 v2](https://img.shields.io/badge/x402-v2-7B61FF)](https://github.com/coinbase/x402)\n\n</div>\n\n---\n\n## Table of contents\n\n- [Why this package exists](#why-this-package-exists)\n- [Install](#install)\n- [Quick start](#quick-start)\n  - [1. Auto-DID wallet](#1-auto-did-wallet-agentsmd-v122-a--d)\n  - [2. Self-hosted facilitator with x402.org fallback](#2-self-hosted-facilitator-with-x402org-fallback-agentsmd-v122-e)\n  - [3. Hono server (paywall route)](#3-hono-server-paywall-route)\n  - [4. Fetch client (Rover)](#4-fetch-client-rover)\n- [What this package re-exports from `@x402/*`](#what-this-package-re-exports-from-x402)\n- [What AIVO adds on top](#what-aivo-adds-on-top)\n- [Failure semantics](#failure-semantics)\n- [Publishing & releases](#publishing--releases)\n- [Architecture diagram](#architecture-diagram)\n- [License](#license)\n\n---\n\n## Why this package exists\n\nThe AIVO stack has three repos that need to talk to each other over x402:\n\n| Repo | Role | Talks x402 as… |\n|---|---|---|\n| [`aivo-swarm`](../aivo-swarm) | Pool intel API | **Server** (paywall routes) |\n| [`rover`](../rover) | LP agent | **Client** (auto-pays Swarm) |\n| **`x402-solana`** (this) | Shared protocol | **Both** + AIVO helpers |\n\nTwo pieces are unique to AIVO and **not** in the upstream `@x402/*` packages:\n\n1. **Auto-DID wallet flow** — wallet pubkey = identity, no registration. Swarm upserts on first contact.\n2. **Self-hosted facilitator with fallback** — run our own facilitator, fall back to `x402.org` if it dies.\n\nBoth come from [AGENTS.md v1.2.2](../AGENTS.md). This package is the implementation.\n\n---\n\n## Install\n\n```bash\nnpm install @aivo-x402/solana\n```\n\n**Requirements:** Node.js ≥ 22.12, TypeScript ≥ 5.0, ESM-only.\n\n---\n\n## Quick start\n\n### 1. Auto-DID wallet ([AGENTS.md v1.2.2 a–d](../AGENTS.md))\n\nWallet = identity. `did:sol:<pubkey>` per W3C DID spec for Solana. No signup, no API key.\n\n```ts\nimport { createDID, verifyWallet, walletFromDID } from \"@aivo-x402/solana\";\nimport nacl from \"tweetnacl\";\n\n// ── Server (Swarm) ──────────────────────────────────────────\n// Derive a DID from any wallet that pings you. Upsert on first contact.\nconst did = createDID(\"AGwiTnRnXCgf9AemWdvTwWDz18YUevTGDv2TokT97n1Q\");\n// → { id: \"did:sol:AGwiT...\", controller: \"AGwiT...\", created: \"2026-06-02T...\" }\n\n// Extract the pubkey back out of a DID string\nconst wallet = walletFromDID(\"did:sol:AGwiTnRnXCgf9AemWdvTwWDz18YUevTGDv2TokT97n1Q\");\n// → \"AGwiTnRnXCgf9AemWdvTwWDz18YUevTGDv2TokT97n1Q\"\n\n// ── Client (Rover) ──────────────────────────────────────────\n// Prove wallet ownership by signing a payload (e.g. the request body)\nconst keypair = nacl.sign.keyPair.fromSeed(seed);\nconst payload = new TextEncoder().encode(JSON.stringify({ pool: \"X\" }));\nconst signature = nacl.sign.detached(payload, keypair.secretKey);\n\nconst isValid = verifyWallet({\n  payload,\n  signature,\n  wallet: keypair.publicKey.toBase58(),\n});\n// → true / false\n```\n\n**Why this is nice:** one wallet works across Swarm + Rover + (future) `@aivo-x402/solana` consumers. No separate registration, no API keys, no friction.\n\n---\n\n### 2. Self-hosted facilitator with x402.org fallback ([AGENTS.md v1.2.2 e](../AGENTS.md))\n\n```ts\nimport {\n  createFacilitator,\n  x402ResourceServer,\n  ExactSvmScheme,\n  X402FacilitatorUnavailableError,\n} from \"@aivo-x402/solana\";\n\nconst facilitator = createFacilitator({\n  selfHostUrl: process.env.X402_FACILITATOR_PRIMARY, // e.g. https://x402.aivo.sh\n  fallbackUrl: \"https://x402.org\",\n  timeoutMs: 15_000,\n  onFallback: (reason) => console.warn(`[x402] falling back: ${reason}`),\n});\n\nconst server = new x402ResourceServer(\n  new ExactSvmScheme(/* signer config */),\n);\n\n// Use the facilitator to verify/settle payments\ntry {\n  const result = await facilitator.verify({ paymentPayload, accepted });\n  if (!result.isValid) throw new Error(\"payment rejected\");\n} catch (err) {\n  if (err instanceof X402FacilitatorUnavailableError) {\n    // Both self-host AND x402.org are down — fail closed\n    throw err;\n  }\n  throw err;\n}\n```\n\nThe order of resolution is:\n\n```\n1. selfHostUrl  (your own facilitator — lowest latency, no per-tx fee)\n       ↓ if unavailable / 5xx / timeout / network error\n2. fallbackUrl  (x402.org — Coinbase + Cloudflare, public)\n       ↓ if still failing\n3. throw X402FacilitatorUnavailableError\n```\n\nSee [Failure semantics](#failure-semantics) for details.\n\n---\n\n### 3. Hono server (paywall route)\n\n```ts\nimport { Hono } from \"hono\";\nimport {\n  paymentMiddleware,\n  RoutesConfig,\n  ExactSvmScheme,\n  x402ResourceServer,\n} from \"@aivo-x402/solana\";\n\nconst app = new Hono();\n\nconst routes: RoutesConfig = {\n  \"GET /v1/pools/top\": {\n    accepts: {\n      scheme: \"exact\",\n      network: \"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\",\n      payTo: \"AGwiTnRnXCgf9AemWdvTwWDz18YUevTGDv2TokT97n1Q\",\n      price: \"$0.001\",\n    },\n    description: \"Top N pools by composite score\",\n  },\n};\n\nconst server = new x402ResourceServer(new ExactSvmScheme(/* signer */));\n\napp.use(\n  paymentMiddleware(\n    routes,\n    server, // x402ResourceServer (handles facilitator internally)\n  ),\n);\n\napp.get(\"/v1/pools/top\", (c) => c.json({ pools: [] }));\n```\n\n---\n\n### 4. Fetch client (Rover)\n\n```ts\nimport {\n  wrapFetchWithPayment,\n  x402Client,\n  ExactSvmScheme,\n} from \"@aivo-x402/solana\";\n\nconst client = new x402Client().register(\n  \"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\",\n  new ExactSvmScheme({ /* signer config */ }),\n);\n\nconst paidFetch = wrapFetchWithPayment(fetch, client);\nconst res = await paidFetch(\"https://swarm.example.com/v1/pools/top\");\n// → automatically retries 402 with payment, then returns the data\n```\n\n---\n\n## What this package re-exports from `@x402/*`\n\nYou can import everything from `@aivo-x402/solana` instead of juggling scoped names.\n\n| From | What you get |\n|---|---|\n| `@x402/core/types` | `PaymentPayload`, `PaymentRequired`, `PaymentRequirements`, `ResourceInfo`, `Network`, `VerifyResponse`, `SettleResponse` |\n| `@x402/core/server` | `x402ResourceServer`, `x402HTTPResourceServer`, `FacilitatorClient`, `RoutesConfig`, `RouteConfig` |\n| `@x402/core/http` | `encodePaymentRequiredHeader`, `decodePaymentSignatureHeader` (base64 wire helpers) |\n| `@x402/fetch` | `x402Client`, `x402HTTPClient`, `wrapFetchWithPayment` |\n| `@x402/hono` | `paymentMiddleware`, `paymentMiddlewareFromConfig` |\n| `@x402/svm` | `ExactSvmScheme`, `ClientSvmConfig`, `FacilitatorRpcConfig` |\n| `@x402/extensions` | Bazaar, sign-in-with-x, etc. (re-exported as a pass-through) |\n\nFor the full API surface, see the upstream docs at [coinbase/x402](https://github.com/coinbase/x402/tree/main/typescript).\n\n---\n\n## What AIVO adds on top\n\n| Export | Purpose |\n|---|---|\n| `createDID(wallet)` | Derive `did:sol:<pubkey>` from a Solana pubkey (W3C DID) |\n| `getDID(wallet)` | Alias of `createDID` for symmetry with \"get\" semantics |\n| `verifyWallet({ payload, signature, wallet })` | Ed25519 signature verification via `tweetnacl` |\n| `walletFromDID(did)` | Extract the pubkey back from a `did:sol:` string |\n| `createFacilitator({ selfHostUrl?, fallbackUrl?, timeoutMs?, onFallback? })` | Self-host → fallback chain facilitator client |\n| `X402FacilitatorUnavailableError` | Thrown when **both** facilitators fail |\n| `AivoFacilitator` (type) | Shape of the returned facilitator client |\n\nThe DID helpers do **not** persist anything — they're pure derivation functions. Storage of the DID ↔ wallet mapping is the caller's responsibility (Swarm stores in Postgres, Rover keeps it in memory per session).\n\n---\n\n## Failure semantics\n\nThe facilitator wrapper is opinionated about what counts as a \"real\" failure:\n\n| Outcome | Action |\n|---|---|\n| 2xx from self-host | Use the response, **no fallback** |\n| 4xx from self-host | Return the body as-is — `isValid: false` is a legitimate answer, do **not** fall back |\n| 5xx from self-host | Fall back to `fallbackUrl` |\n| Network error / timeout on self-host | Fall back to `fallbackUrl` |\n| 2xx from fallback | Use the response, log via `onFallback` |\n| Fallback also fails (5xx / network / timeout) | Throw `X402FacilitatorUnavailableError` |\n| 4xx from fallback | Return the body as-is (legitimate rejection) |\n\nThis matches the AGENTS.md spec: \"Never let Swarm serve data without facilitator verification — that breaks the paywall. Fail closed, not open.\"\n\n---\n\n## Publishing & releases\n\nTagged releases are published to npm automatically via [`.github/workflows/release.yml`](./.github/workflows/release.yml).\n\n### One-time setup (maintainer)\n\n1. Create an npm **granular access token** with `publish` scope on `@aivo-x402/solana`.\n2. Add it to the repo as a GitHub secret: `NPM_TOKEN`.\n3. Repo already has `id-token: write` permission for npm provenance attestation.\n\n### Cutting a release\n\n```bash\n# 1. Bump version in package.json\n# 2. Move [Unreleased] → dated version in CHANGELOG.md\n# 3. Commit, tag, push\ngit add package.json CHANGELOG.md\ngit commit -m \"chore: release v0.1.0\"\ngit tag v0.1.0\ngit push origin main --tags\n```\n\nCI will:\n\n1. ✅ Install deps, typecheck, lint, test, build\n2. 📦 Upload `dist/` artifact\n3. 🚀 Publish to npm with `--provenance --access public`\n\nYou can also trigger a **dry run** manually from the Actions tab without publishing.\n\n---\n\n## Architecture diagram\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                  USER / AGENT                            │\n└────────────┬─────────────────────────┬───────────────────┘\n             │                         │\n     (1) API │                         │ (2) run rover binary\n   $0.001+   │                         │     (revenue: Swarm + Jupiter)\n   USDC      │                         │\n             ▼                         ▼\n   ┌─────────────────┐         ┌─────────────────┐\n   │   aivo-swarm    │◀──HMAC──│      rover      │\n   │  (Hono + DBOS)  │ beacon  │ (Hono + Mastra) │\n   │                 │         │                 │\n   │ • pool scoring  │         │ • screener      │\n   │ • LLM judge     │         │ • position mgr  │\n   │ • x402 paywall  │         │ • x402 client   │\n   └────────┬────────┘         └────────┬────────┘\n            │                          │\n            │ (3) self-pay             │ (4) swap volume\n            │     USDC x402            │     kickback 0.1–0.3%\n            ▼                          ▼\n   ┌──────────────────────────────────────────────────┐\n   │          @aivo-x402/solana  (this package)       │\n   │  • Re-exports @x402/* (core, svm, hono, fetch)   │\n   │  • createDID / verifyWallet (auto-DID)           │\n   │  • createFacilitator (self-host → x402.org)      │\n   └──────────────────────────────────────────────────┘\n            │                          │\n            ▼                          ▼\n   Self-hosted facilitator     Jupiter Referral Program\n   (aivo-sh) → fallback:       (referralAccount hardcoded)\n   https://x402.org            → 0.1–0.3% kickback\n```\n\n---\n\n## License\n\n[MIT](./LICENSE) — © 2026 AIVO.\n\nBuilt on the open [x402 protocol](https://github.com/coinbase/x402) by Coinbase & Cloudflare. ❤️\n","readmeFilename":"README.md"}