{"_id":"@agentallowance/sdk","name":"@agentallowance/sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@agentallowance/sdk","version":"0.1.1","description":"Bounded, autonomous x402 payments for AI agents on Stellar.","license":"MIT","type":"module","keywords":["stellar","soroban","x402","ai-agents","smart-account","payments"],"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"engines":{"node":">=22.18.0"},"repository":{"type":"git","url":"git+https://github.com/karagozemin/AgentAllowance.git","directory":"packages/sdk"},"homepage":"https://github.com/karagozemin/AgentAllowance#readme","bugs":{"url":"https://github.com/karagozemin/AgentAllowance/issues"},"publishConfig":{"access":"public"},"dependencies":{"@stellar/stellar-sdk":"16.2.0","@agentallowance/shared":"^0.1.1","@agentallowance/stellar-smart-account-auth":"^0.1.1","@agentallowance/x402-payer":"^0.1.1"},"devDependencies":{"@types/node":"24.10.1","typescript":"5.9.3","vitest":"4.0.15"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run"},"_id":"@agentallowance/sdk@0.1.1","_integrity":"sha512-dWEUlqZVJCN66H4DNtIiklMQHPSBhmhSsP+KfynHV7PPK/u222eo+8lywtP8UmJ7R4/1yDZ0gRiXxY2D/c3zag==","_resolved":"/private/var/folders/1j/05xhzsh928n2c506c1v41dhc0000gn/T/129bcc175127f7ccbd95ba9b3ba07b89/agentallowance-sdk-0.1.1.tgz","_from":"file:agentallowance-sdk-0.1.1.tgz","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-dWEUlqZVJCN66H4DNtIiklMQHPSBhmhSsP+KfynHV7PPK/u222eo+8lywtP8UmJ7R4/1yDZ0gRiXxY2D/c3zag==","shasum":"a6edfb16f6fe2c9cc79713e6861c154d40855047","tarball":"https://registry.npmjs.org/@agentallowance/sdk/-/sdk-0.1.1.tgz","fileCount":27,"unpackedSize":116041,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH3V73PAHN8b1urqM4hHc+r8gBtniKQYEFVKsp8axvX6AiBKCpfJugPZrBYdNE1DtSpqxIV1GOeoDAdZsFV6smQX4g=="}]},"_npmUser":{"name":"kaptan_web3","email":"eminkaragoz07@gmail.com"},"directories":{},"maintainers":[{"name":"kaptan_web3","email":"eminkaragoz07@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.1_1785871293611_0.8889406042248826"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-04T19:21:33.338Z","0.1.1":"2026-08-04T19:21:33.780Z","modified":"2026-08-04T19:21:34.061Z"},"maintainers":[{"name":"kaptan_web3","email":"eminkaragoz07@gmail.com"}],"description":"Bounded, autonomous x402 payments for AI agents on Stellar.","homepage":"https://github.com/karagozemin/AgentAllowance#readme","keywords":["stellar","soroban","x402","ai-agents","smart-account","payments"],"repository":{"type":"git","url":"git+https://github.com/karagozemin/AgentAllowance.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/karagozemin/AgentAllowance/issues"},"license":"MIT","readme":"# @agentallowance/sdk\n\nGive AI agents a budget, not your wallet.\n\n`@agentallowance/sdk` is the server-side TypeScript SDK for bounded, autonomous x402 payments on\nStellar. It creates and revokes smart-account allowances, validates payment challenges, constructs\ndelegated Soroban authorization, verifies settlement receipts, and keeps normalized evidence for\nreconciliation.\n\n> Testnet-first, unaudited software. Do not use this release for production custody.\n\n## Install\n\n```bash\nnpm install @agentallowance/sdk @stellar/stellar-sdk\n```\n\nNode.js 22.18 or newer is required. The default evidence store uses `node:sqlite`, so this package is\nintended for trusted server or agent runtimes, not browser bundles.\n\nThe pinned Stellar SDK has an upstream `@stellar/js-xdr` declaration gap. TypeScript consumers should\nenable `skipLibCheck: true`; application source remains strictly checked.\n\n## Pay an x402 service\n\n```ts\nimport { AgentAllowance, SqliteEvidenceStore } from \"@agentallowance/sdk\";\nimport { Keypair } from \"@stellar/stellar-sdk\";\n\nconst delegate = Keypair.fromSecret(process.env.DELEGATED_SIGNER_SECRET!);\nconst feePayer = Keypair.fromSecret(process.env.FEE_PAYER_SECRET!);\n\nconst aa = new AgentAllowance({\n  network: \"stellar:testnet\",\n  rpcUrl: \"https://soroban-testnet.stellar.org\",\n  horizonUrl: \"https://horizon-testnet.stellar.org\",\n  assetContract: process.env.STELLAR_TOKEN_CONTRACT!,\n  treasuryContract: process.env.TREASURY_CONTRACT!,\n  spendingPolicy: process.env.SPENDING_POLICY_CONTRACT!,\n  recipientPolicy: process.env.RECIPIENT_POLICY_CONTRACT!,\n  facilitatorUrl: process.env.X402_FACILITATOR_URL!,\n  transactionSource: feePayer,\n  adminAddress: process.env.ADMIN_ADDRESS!,\n  delegatedSigners: { [delegate.publicKey()]: delegate },\n  store: new SqliteEvidenceStore(\"./data/agentallowance.db\"),\n});\n\nconst response = await aa.fetch(\"https://merchant.example/premium\", {\n  allowanceId: \"2\",\n});\n\nconsole.log(await response.json());\n```\n\n`fetch` performs the complete `402 -> authorization -> verify -> settle -> paid retry` lifecycle. It\naccepts the protected response only when the settlement receipt matches the original network, payer,\nasset, amount, recipient, and challenge reference.\n\n## Core API\n\n```ts\nawait aa.allowances.create(input);\nawait aa.allowances.get(id);\nawait aa.allowances.list();\nawait aa.allowances.revoke(id);\nawait aa.treasury.balance();\n\naa.preflight(requirements, allowance, currentLedger);\nawait aa.pay(challenge, { allowanceId });\nawait aa.fetch(url, { allowanceId });\nawait aa.reconcile(attemptId);\naa.getAttempt(attemptId);\naa.listAttempts();\n```\n\nAdministration can use a backend-held admin signer or the exported wallet preparation/submission\nfunctions for exact Freighter authorization preimages. Delegated payment keys and fee-payer keys must\nremain in isolated server-side signer processes.\n\n## Typed failures\n\n```ts\nimport { AgentAllowanceError } from \"@agentallowance/sdk\";\n\ntry {\n  await aa.fetch(url, { allowanceId: \"2\" });\n} catch (error) {\n  if (error instanceof AgentAllowanceError) {\n    console.error(error.code, error.attemptId, error.safeDetail);\n  }\n}\n```\n\nStable codes distinguish policy denials, malformed challenges, definitive facilitator rejection,\nambiguous settlement, receipt mismatch, and protected-resource failure. An ambiguous settlement must\nbe reconciled; it must not be paid again blindly.\n\n## Documentation\n\n- [Five-minute overview and quickstart](https://github.com/karagozemin/AgentAllowance/blob/main/docs/sdk/quickstart.md)\n- [API reference](https://github.com/karagozemin/AgentAllowance/blob/main/docs/sdk/api-reference.md)\n- [Error reference](https://github.com/karagozemin/AgentAllowance/blob/main/docs/sdk/errors.md)\n- [SDK security model](https://github.com/karagozemin/AgentAllowance/blob/main/docs/sdk/security.md)\n- [Independent integration example](https://github.com/karagozemin/AgentAllowance/tree/main/apps/x402-sdk-example)\n- [Testnet evidence](https://github.com/karagozemin/AgentAllowance/blob/main/docs/submission/evidence-index.md)\n\nMIT licensed.\n","readmeFilename":"README.md","_rev":"1-e89973f98eec3be0de6e918357766f5b"}