{"_id":"@apirail/payer-sdk","name":"@apirail/payer-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@apirail/payer-sdk","version":"0.1.0","description":"Payer SDK for PoAPW - Proof of API-Work protocol. Call APIs and pay with Cardano native tokens.","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"keywords":["poapw","cardano","api","payment","blockchain","native-tokens","web3","cryptocurrency","ada","api-monetization"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/poapw/poapw-sdk.git"},"homepage":"https://github.com/poapw/poapw-sdk#readme","bugs":{"url":"https://github.com/poapw/poapw-sdk/issues"},"engines":{"node":">=18.0.0"},"devDependencies":{"typescript":"^5.0.0"},"gitHead":"e8e844356443e478784b604fcf34f53c1123418c","_id":"@apirail/payer-sdk@0.1.0","_nodeVersion":"25.5.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-hZYtkKCdxysmHHAv9UhzMOfHtZOjBpAqzMjyVOfYdZw4FEgj/JypWJ/7b/9TGanjQ8jLjeNIQog9Wi2Dv5Pm1w==","shasum":"52c37da2e20bf8fdf9ef7d06481964752838eed3","tarball":"https://registry.npmjs.org/@apirail/payer-sdk/-/payer-sdk-0.1.0.tgz","fileCount":4,"unpackedSize":38072,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBlEXDVrq2dsKeej3tvNc4CsAjN8/5LdkOLKZCRRhT0jAiEA6hmF457uJ9tMXg+l9X+ynZ9gg0WqFarqN1OaqSwtQJ4="}]},"_npmUser":{"name":"apirail","email":"jog@compucampus.de"},"directories":{},"maintainers":[{"name":"apirail","email":"jog@compucampus.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/payer-sdk_0.1.0_1770295699327_0.508066176022363"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-05T12:48:19.251Z","0.1.0":"2026-02-05T12:48:19.476Z","modified":"2026-02-05T12:48:19.654Z"},"maintainers":[{"name":"apirail","email":"jog@compucampus.de"}],"description":"Payer SDK for PoAPW - Proof of API-Work protocol. Call APIs and pay with Cardano native tokens.","homepage":"https://github.com/poapw/poapw-sdk#readme","keywords":["poapw","cardano","api","payment","blockchain","native-tokens","web3","cryptocurrency","ada","api-monetization"],"repository":{"type":"git","url":"git+https://github.com/poapw/poapw-sdk.git"},"bugs":{"url":"https://github.com/poapw/poapw-sdk/issues"},"license":"MIT","readme":"# @apirail/payer-sdk\n\nPayer SDK for PoAPW (Proof of API-Work) - A machine-native settlement protocol where APIs earn Cardano native tokens by delivering results.\n\n## Installation\n\n```bash\nnpm install @apirail/payer-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { PayerSDK } from '@apirail/payer-sdk';\n\nconst payer = new PayerSDK({\n  baseUrl: 'https://your-poapw-server.com',\n  walletId: 'your-wallet-id',\n});\n\n// Call an API - payments are handled automatically\nconst result = await payer.callApi('api-route-id', { data: 'your-payload' });\n\nif (result.success) {\n  console.log('Response:', result.response);\n  console.log('Response time:', result.responseTimeMs, 'ms');\n}\n```\n\n## Features\n\n- **Auto-Settle**: Automatically settles on-chain when payment threshold is reached (enabled by default)\n- **Off-chain Accumulation**: API calls accumulate off-chain until threshold, minimizing transaction costs\n- **Type-safe**: Full TypeScript support with exported interfaces\n\n## Configuration\n\n```typescript\nconst payer = new PayerSDK({\n  baseUrl: 'https://your-poapw-server.com',  // Required: PoAPW server URL\n  walletId: 'your-wallet-id',                 // Required: Your payer wallet ID\n  paymentMode: 'native',                      // Optional: 'native' or 'masumi' (default: 'native')\n  autoSettle: true,                           // Optional: Auto-pay when threshold reached (default: true)\n  onPaymentRequired: async (details) => {     // Optional: Custom settlement logic\n    console.log('Payment required:', details.accumulatedAmount, 'tokens');\n    return true; // Return true to settle, false to skip\n  },\n  onSettlement: (result) => {                 // Optional: Settlement callback\n    console.log('Settled:', result.settledAmount, 'TX:', result.txHash);\n  },\n  onMasumiJob: (job) => {                     // Optional: Masumi job callback\n    console.log('Masumi job started:', job.id);\n  },\n});\n```\n\n## Payment Modes\n\nThe SDK supports two payment modes:\n\n### Native Mode (default)\nUses PoAPW's native token payment system with off-chain accumulation and batch settlement.\n\n```typescript\nconst payer = new PayerSDK({\n  baseUrl: 'https://your-server.com',\n  walletId: 'your-wallet-id',\n  paymentMode: 'native',\n});\n```\n\n### Masumi Mode\nUses the Masumi Network protocol for AI agent payments with smart contract escrow.\n\n```typescript\nconst payer = new PayerSDK({\n  baseUrl: 'https://your-server.com',\n  walletId: 'your-wallet-id',\n  paymentMode: 'masumi',\n});\n\n// Or switch modes at runtime\npayer.setPaymentMode('masumi');\n```\n\n## API Reference\n\n### `callApi<T>(apiRouteId: string, payload?: unknown): Promise<ApiCallResult<T>>`\n\nCall a registered API. Handles payment flow automatically.\n\n```typescript\nconst result = await payer.callApi('api-id', { message: 'Hello' });\n// result.success, result.response, result.httpStatus, result.responseTimeMs\n```\n\n### `getBalances(): Promise<BalanceInfo[]>`\n\nGet accumulated balances for all receivers.\n\n```typescript\nconst balances = await payer.getBalances();\n// [{ receiverId, accumulatedAmount, paidAmount }]\n```\n\n### `settleBalance(receiverId: string): Promise<SettlementResult>`\n\nManually trigger on-chain settlement for a receiver.\n\n```typescript\nconst result = await payer.settleBalance('receiver-wallet-id');\n// result.success, result.txHash, result.settledAmount\n```\n\n### `getAvailableApis(): Promise<ApiRouteInfo[]>`\n\nList all available APIs on the network.\n\n```typescript\nconst apis = await payer.getAvailableApis();\n// [{ id, name, endpoint, method, basePrice }]\n```\n\n### `getWalletInfo(): Promise<WalletInfo>`\n\nGet your wallet information including balance.\n\n```typescript\nconst wallet = await payer.getWalletInfo();\n// { id, name, balance, cardanoAddress }\n```\n\n## Payment Flow\n\n1. **Call API** - SDK sends request to PoAPW server\n2. **Off-chain Accumulation** - Tokens accumulate until threshold\n3. **402 Response** - When threshold reached, server returns 402\n4. **Auto-Settle** - SDK automatically settles on-chain (if enabled)\n5. **Retry** - SDK retries the API call after settlement\n6. **Success** - API response returned to caller\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-bf3564c7000fc382a47273abf257552a"}