{"_id":"@agenticocean/x402-stellar","_rev":"2-6ce2cf2aef5f2d92e7b89a6c2c61a015","name":"@agenticocean/x402-stellar","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@agenticocean/x402-stellar","version":"1.0.0","keywords":["stellar","soroban","x402","payment","ai-agents","defi","blockchain"],"license":"MIT","_id":"@agenticocean/x402-stellar@1.0.0","maintainers":[{"name":"solbinary","email":"nishantsharmay2@gmail.com"}],"homepage":"https://stellaragent402.io","bugs":{"url":"https://github.com/stellaragent402/stellaragent402/issues"},"dist":{"shasum":"35e84071269cf39076e77ada085d147bbf9a9ae8","tarball":"https://registry.npmjs.org/@agenticocean/x402-stellar/-/x402-stellar-1.0.0.tgz","fileCount":34,"integrity":"sha512-0P8Ll9Jsx7TlTCZvYNBAeX/EsmOjGLZlmRsNXvn8Q0NGnV3zXcmy/9zuKLEYRrdiUXFiSsESQbjyd2UFtaqzvg==","signatures":[{"sig":"MEUCIQCvdHe816olr4NWY907m08j+PIrfe0IDvQhpqS7PQ8NMAIgfNkKPvqGhECg2H6+Abp9Nu05/S7BGY1qi7zIuo4BuEU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49673},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"2242808e0849d94e973fe16cb81470ef70c08eeb","scripts":{"lint":"tsc --noEmit","build":"tsc","clean":"rm -rf dist"},"_npmUser":{"name":"solbinary","email":"nishantsharmay2@gmail.com"},"repository":{"url":"git+https://github.com/stellaragent402/stellaragent402.git","type":"git"},"_npmVersion":"10.8.2","description":"x402 payment protocol for Stellar — header builder, facilitator, Express middleware","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@stellar/stellar-sdk":"^13.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/express":"^5.0.0"},"peerDependencies":{"express":">=4.0.0"},"peerDependenciesMeta":{"express":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/x402-stellar_1.0.0_1771650830103_0.36484503587083017","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@agenticocean/x402-stellar","version":"1.0.1","description":"x402 payment protocol for Stellar — header builder, facilitator, Express middleware","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","lint":"tsc --noEmit","clean":"rm -rf dist"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/stellaragent402/stellaragent402.git"},"homepage":"https://stellaragent402.io","bugs":{"url":"https://github.com/stellaragent402/stellaragent402/issues"},"keywords":["stellar","soroban","x402","payment","ai-agents","defi","blockchain"],"dependencies":{"@stellar/stellar-sdk":"^14.5.0"},"peerDependencies":{"express":">=4.0.0"},"peerDependenciesMeta":{"express":{"optional":true}},"devDependencies":{"@types/express":"^5.0.0","typescript":"^5.7.0"},"license":"MIT","_id":"@agenticocean/x402-stellar@1.0.1","gitHead":"74cfd509b1123d1bd99ea3f0772ac9429131aa97","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-nIwnLLaqeno1rY+THE6qE7Iv/dx22YX6we9WYEZe4ScsyTjk6ug9RSrftoka3ZxCpVw+XVkya4Id8Ca9CxTxtA==","shasum":"68b10cf6b1ebc6ba89e60cc2cc386523e7d185e7","tarball":"https://registry.npmjs.org/@agenticocean/x402-stellar/-/x402-stellar-1.0.1.tgz","fileCount":34,"unpackedSize":50739,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCIg75dJ0a1S05EgWoDS1eT4WifXei1wPOolI1QDgvssgIhAI9ZAHAZGbgh9ZMZ9wuMCcUvhk0FJVX+8Tx4eeJhnVeV"}]},"_npmUser":{"name":"solbinary","email":"nishantsharmay2@gmail.com"},"directories":{},"maintainers":[{"name":"solbinary","email":"nishantsharmay2@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x402-stellar_1.0.1_1771827025378_0.7511386634622494"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-21T05:13:49.988Z","modified":"2026-02-23T06:10:25.946Z","1.0.0":"2026-02-21T05:13:50.250Z","1.0.1":"2026-02-23T06:10:25.512Z"},"bugs":{"url":"https://github.com/stellaragent402/stellaragent402/issues"},"license":"MIT","homepage":"https://stellaragent402.io","keywords":["stellar","soroban","x402","payment","ai-agents","defi","blockchain"],"repository":{"type":"git","url":"git+https://github.com/stellaragent402/stellaragent402.git"},"description":"x402 payment protocol for Stellar — header builder, facilitator, Express middleware","maintainers":[{"name":"solbinary","email":"nishantsharmay2@gmail.com"}],"readme":"# @agenticocean/x402-stellar\n\nx402 payment protocol for Stellar — header builder, facilitator, and Express middleware for AI agent micropayments.\n\n## Installation\n\n```bash\nnpm install @agenticocean/x402-stellar\n# or\npnpm add @agenticocean/x402-stellar\n```\n\n## Quick Start\n\n### 1. Build an x402 Payment Header (Agent side)\n\n```typescript\nimport { buildX402Header } from \"@agenticocean/x402-stellar\";\n\nconst header = await buildX402Header({\n  rpcUrl: \"https://soroban-testnet.stellar.org\",\n  networkPassphrase: \"Test SDF Network ; September 2015\",\n  vaultContract: \"CVAULT...\",\n  agentSigner: \"GAGENT...\",\n  agentSecret: \"SAGENT_SECRET...\",\n  payTo: \"GFACILITATOR...\",\n  amount: \"100000\",        // 0.01 USDC in stroops\n  memo: \"yield_query_v1\",\n  agentId: 1,\n  usdcAddress: \"CUSDC...\",\n});\n\n// Use in API request\nconst response = await fetch(\"https://api.example.com/yield/query\", {\n  headers: { \"X-PAYMENT\": header },\n});\n```\n\n### 2. Gate your API with x402 Middleware (Vendor side)\n\n```typescript\nimport express from \"express\";\nimport { createX402Middleware } from \"@agenticocean/x402-stellar\";\n\nconst app = express();\n\nconst x402 = createX402Middleware({\n  rpcUrl: \"https://soroban-testnet.stellar.org\",\n  horizonUrl: \"https://horizon-testnet.stellar.org\",\n  networkPassphrase: \"Test SDF Network ; September 2015\",\n  facilitatorSecret: process.env.FACILITATOR_SECRET!,\n  usdcAddress: \"CUSDC...\",\n});\n\n// Gate a route — returns 402 if unpaid, 200 if paid\napp.get(\"/premium-data\", x402({ price: \"100000\", description: \"Premium AI data\" }), (req, res) => {\n  res.json({ data: \"...\", payment: req.x402 });\n});\n\napp.listen(3001);\n```\n\n### 3. Settle a Payment (Facilitator side)\n\n```typescript\nimport { settlePayment } from \"@agenticocean/x402-stellar\";\n\nconst result = await settlePayment(paymentPayload, {\n  rpcUrl: \"https://soroban-testnet.stellar.org\",\n  horizonUrl: \"https://horizon-testnet.stellar.org\",\n  networkPassphrase: \"Test SDF Network ; September 2015\",\n  facilitatorSecret: process.env.FACILITATOR_SECRET!,\n});\n\nconsole.log(result.success, result.txHash);\n```\n\n## API Reference\n\n### `buildX402Header(params)`\n\nBuilds a base64-encoded x402 payment header. Signs a `vault.agent_pay()` invocation with the agent's key.\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `rpcUrl` | `string` | Soroban RPC endpoint |\n| `networkPassphrase` | `string` | Network passphrase |\n| `vaultContract` | `string` | User vault contract address |\n| `agentSigner` | `string` | Agent's public key |\n| `agentSecret` | `string` | Agent's secret key (for signing auth entry) |\n| `payTo` | `string` | Facilitator's public key (payment destination) |\n| `amount` | `string` | Amount in stroops (7 decimals) |\n| `memo` | `string` | Audit memo |\n| `agentId` | `number` | Agent's registry ID |\n| `usdcAddress` | `string` | USDC SAC contract address |\n\n### `createX402Middleware(options)`\n\nReturns an Express middleware factory. Call with route config to create per-route middleware.\n\n```typescript\nconst x402 = createX402Middleware({ ...options });\n\n// Returns middleware:\nx402({ price: \"100000\", description: \"...\" })\n```\n\n### `settlePayment(payload, options)`\n\nVerifies and executes payment on-chain. Returns `{ success, txHash?, error? }`.\n\n### `formatUsdc(stroops)`\n\nConvert stroops to human-readable USDC string.\n\n```typescript\nformatUsdc(\"100000\")    // → \"0.01\"\nformatUsdc(10_000_000n) // → \"1.00\"\n```\n\n### `toStroops(usdc)`\n\nConvert USDC amount to stroops (bigint).\n\n```typescript\ntoStroops(0.01) // → 100000n\ntoStroops(5)    // → 50000000n\n```\n\n### Network Config\n\n```typescript\nimport { TESTNET, MAINNET } from \"@agenticocean/x402-stellar\";\n\n// TESTNET: soroban-testnet.stellar.org\n// MAINNET: soroban.stellar.org\n```\n\n## Stellar USDC Decimals\n\n**Important**: Stellar USDC uses 7 decimal places (not 6 like EVM).\n\n- `1 USDC = 10,000,000 stroops`\n- `0.01 USDC = 100,000 stroops`\n\n## How It Works\n\nThe x402 flow on Stellar:\n\n1. Agent requests a paid route → receives `402 Payment Required` with amount + facilitator address\n2. Agent builds a `vault.agent_pay()` Soroban invocation, simulates it to get the auth entry + footprint\n3. Agent signs the `SorobanAuthorizationEntry` with their key (anti-replay nonce included)\n4. Agent sends the assembled transaction XDR + signed auth entry in the `X-PAYMENT` header\n5. Facilitator deserializes the pre-assembled tx, signs as source (pays XLM fees), submits\n6. Soroban verifies agent's signature, enforces daily spending limit, transfers USDC\n7. Route returns `200 OK` with strategy + `X-PAYMENT-RESPONSE: { txHash }`\n\n## License\n\nMIT — AgenticOcean\n","readmeFilename":"README.md"}