{"id":51045596,"url":"https://github.com/selfradiance/x402-spend-receipt","last_synced_at":"2026-06-22T13:32:22.277Z","repository":{"id":363950875,"uuid":"1265695309","full_name":"selfradiance/x402-spend-receipt","owner":"selfradiance","description":"Local policy gate + signed, hash-chained allow/deny receipts for x402 agent payments","archived":false,"fork":false,"pushed_at":"2026-06-21T13:25:21.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T15:17:56.860Z","etag":null,"topics":["agent-payments","agentic-commerce","ai-agents","ai-safety","audit-log","audit-trail","cli","ed25519","http-402","micropayments","payment-receipts","policy-engine","receipts","tamper-evident","typescript","x402"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/selfradiance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T02:18:29.000Z","updated_at":"2026-06-21T13:25:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/selfradiance/x402-spend-receipt","commit_stats":null,"previous_names":["selfradiance/x402-spend-receipt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/selfradiance/x402-spend-receipt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfradiance%2Fx402-spend-receipt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfradiance%2Fx402-spend-receipt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfradiance%2Fx402-spend-receipt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfradiance%2Fx402-spend-receipt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/selfradiance","download_url":"https://codeload.github.com/selfradiance/x402-spend-receipt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selfradiance%2Fx402-spend-receipt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34651748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-payments","agentic-commerce","ai-agents","ai-safety","audit-log","audit-trail","cli","ed25519","http-402","micropayments","payment-receipts","policy-engine","receipts","tamper-evident","typescript","x402"],"created_at":"2026-06-22T13:32:22.157Z","updated_at":"2026-06-22T13:32:22.271Z","avatar_url":"https://github.com/selfradiance.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# x402-spend-receipt\n\nLocal policy checks and signed receipts for x402 payment intents.\n\n`x402-spend-receipt` is an artifact layer. It evaluates an AI agent's proposed x402 payment intent against a local JSON policy before payment, then writes an Ed25519-signed, hash-chained receipt for the decision.\n\nIt records both `ALLOW` and `DENY` decisions.\n\n## What This Does Not Do\n\nThis package does not make payments. It does not touch funds, wallets, wallet private keys, payment credentials, or hosted services. It does not proxy traffic. It does not call the network.\n\nEverything runs locally and deterministically. Malformed or unknown inputs default to deny.\n\n## Install\n\n```bash\nnpm install -g x402-spend-receipt\n```\n\nOr run it through `npx`:\n\n```bash\nnpx x402-spend-receipt --help\n```\n\nRequires Node.js 20 or newer.\n\n## Initialize Local State\n\n```bash\nnpx x402-spend-receipt init\n```\n\nThis creates local files under:\n\n```text\n~/.config/x402-spend-receipt/\n```\n\nIt writes:\n\n- `ed25519.private.key`\n- `ed25519.public.key`\n- `policy.json`\n- `ledger.sqlite`\n\nThe private key file is created with mode `600`.\n\n## Policy File\n\nThe generated `policy.json` contains exactly the five v0.1 policy rules:\n\n```json\n{\n  \"max_per_payment_base_units\": \"1000000\",\n  \"session_budget_base_units\": \"10000000\",\n  \"pay_to_allowlist\": [\"replace-with-payment-address\"],\n  \"endpoint_host_allowlist\": [\"api.example.com\"],\n  \"repeat_payment_rule\": {\n    \"max_repeats\": 2,\n    \"window_seconds\": 60\n  }\n}\n```\n\nAmounts are integer strings in base units. For USDC, `1000000` means 1.000000 USDC.\n\n## Intent File\n\nAn intent JSON file must look like this:\n\n```json\n{\n  \"method\": \"x402\",\n  \"endpoint_url\": \"https://api.example.com/metered\",\n  \"pay_to\": \"replace-with-payment-address\",\n  \"asset\": \"USDC\",\n  \"network\": \"base\",\n  \"amount_base_units\": \"1000000\",\n  \"agent_urn\": \"urn:agent:demo\"\n}\n```\n\n`amount_base_units` must be a non-negative integer string. Floats, negative values, numbers, extra fields, and malformed JSON are denied.\n\n## Check an Intent\n\n```bash\nnpx x402-spend-receipt check intent.json\n```\n\nExit codes:\n\n- `0` means `ALLOW`\n- `1` means `DENY`\n\nThe command prints JSON with the decision, reason code, and signed receipt.\n\n## Verify One Receipt\n\n```bash\nnpx x402-spend-receipt verify receipt.json --pubkey \"$(cat ~/.config/x402-spend-receipt/ed25519.public.key)\"\n```\n\nThis verifies the receipt signature offline.\n\n## Verify the Ledger Chain\n\n```bash\nnpx x402-spend-receipt verify-chain\n```\n\nThis walks the local SQLite ledger and fails if any receipt hash, previous hash, or signature is broken.\n\n## Export a Receipt\n\n```bash\nnpx x402-spend-receipt export \u003creceipt_id\u003e\n```\n\nThis prints one portable receipt JSON object including the public key.\n\n## Reason Codes\n\nThe fixed reason-code vocabulary is:\n\n```text\nALLOWED\nAMOUNT_EXCEEDS_PER_PAYMENT_MAX\nSESSION_BUDGET_EXCEEDED\nPAY_TO_NOT_ALLOWED\nHOST_NOT_ALLOWED\nREPEAT_PAYMENT_LOOP\nINTENT_INVALID\nPOLICY_INVALID\n```\n\nChecks run in this order, and the first failure wins:\n\n```text\nintent valid\npolicy valid\nper-payment max\nsession budget\npay_to allowlist\nhost allowlist\nrepeat loop\n```\n\n## Wrapper Example\n\nThis example checks an intent before running another command. If the policy check denies the intent, the script aborts before `npx x402-proxy \u003curl\u003e` is run.\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n\nurl=\"https://api.example.com/metered\"\nintent_file=\"$(mktemp)\"\n\ncat \u003e \"$intent_file\" \u003c\u003cJSON\n{\n  \"method\": \"x402\",\n  \"endpoint_url\": \"$url\",\n  \"pay_to\": \"replace-with-payment-address\",\n  \"asset\": \"USDC\",\n  \"network\": \"base\",\n  \"amount_base_units\": \"1000000\",\n  \"agent_urn\": \"urn:agent:demo\"\n}\nJSON\n\nif ! npx x402-spend-receipt check \"$intent_file\" \u003e receipt.json; then\n  echo \"x402 payment intent denied; aborting\"\n  exit 1\nfi\n\nnpx x402-proxy \"$url\"\n```\n\n`x402-spend-receipt` does not run, proxy, or inspect `x402-proxy`. The script simply uses the local receipt check as a gate before running your next command.\n\n## Library\n\nThe package exports the core building blocks used by the CLI:\n\n- `evaluatePolicy`\n- `evaluateAndRecord`\n- `verifyReceipt`\n- `verifyChain`\n- `generateEd25519KeyPair`\n- `SqliteReceiptLedger`\n\n## Development\n\n```bash\nnpm test\nnpm run lint\nnpm run build\n```\n\nLicense: MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselfradiance%2Fx402-spend-receipt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fselfradiance%2Fx402-spend-receipt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselfradiance%2Fx402-spend-receipt/lists"}