{
  "markdown": "# Xaps SDK\n\n**The Cognitive Circuit Breaker for Autonomous Agents**\n\nXaps is an economic security layer for autonomous AI agents. Before executing a smart contract, transfer, or financial action, your agent calls Xaps for an independent dual-agent audit. Standard Web3 tools verify signatures — **Xaps verifies intent and logic**.\n\n<!-- mcp-name: io.github.APMC1/xaps -->\n\n---\n\n## Install\n\n```bash\npip install xaps-sdk\n```\n\nOr install from this repository:\n\n```bash\npip install \"xaps-sdk @ git+https://github.com/APMC1/xaps-sdk.git@v0.1.3\"\n```\n\n## Quick Start\n\n```python\nfrom xaps import XapsClient, XapsRejectedError\n\nclient = XapsClient(api_key=\"your_agent_key\")\n\nreceipt = client.audit(\n    action=\"execute_smart_contract\",\n    contract_address=\"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n    amount=1000.0,\n)\n\naudit = receipt[\"audit\"]\nif audit[\"status\"] == \"REJECTED\":\n    raise XapsRejectedError(audit[\"beta_attack\"], receipt=receipt)\n\nprint(f\"Approved: {audit['alpha_defense']}\")\nprint(f\"Balance remaining: ${receipt['remaining_balance']:.2f}\")\n```\n\n### Async\n\n```python\nfrom xaps import XapsClient\n\nasync with XapsClient(api_key=\"your_agent_key\") as client:\n    receipt = await client.audit_async(\n        action=\"execute_smart_contract\",\n        contract_address=\"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n        amount=1000.0,\n    )\n```\n\n---\n\n## MCP Integration\n\nUse the XAPS MCP server to audit high-stakes actions from Claude Desktop, Cursor, or any MCP host.\nSee [docs/mcp-host-integration.md](docs/mcp-host-integration.md) for full setup.\n\n### Start Using `xaps_audit` in 60 Seconds\n\n1. Install (exposes the `xaps-mcp` console command):\n\n   ```bash\n   pip install xaps-sdk\n   ```\n\n2. Set your agent key in the environment (recommended — avoid storing secrets in config files):\n\n   ```bash\n   export XAPS_AGENT_KEY=\"your_agent_key\"\n   ```\n\n3. Add to Claude Desktop config (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"xaps-audit\": {\n         \"command\": \"xaps-mcp\"\n       }\n     }\n   }\n   ```\n\n   For local dev from a git clone, use `python /path/to/xaps_mcp_server.py` with `XAPS_MCP_DEV=1` instead.\n\n   Full example: [examples/mcp_claude_desktop_config.json](examples/mcp_claude_desktop_config.json)\n\n4. In your agent prompt:\n\n   > Before any `send_transaction`, `approve`, or `deposit` call: invoke `xaps_audit` with `action`, `contract_address`, and `amount`.\n\nAgent rule templates: [examples/.agentrc](examples/.agentrc)\n\n---\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `XAPS_AGENT_KEY` | — | Agent billing key (alternative to constructor arg) |\n| `XAPS_API_URL` | `https://api.xaps.network` | API base URL |\n\n```python\n# Or pass explicitly\nclient = XapsClient(api_key=\"...\", base_url=\"https://api.xaps.network\")\n```\n\n---\n\n## API Reference\n\n### `XapsClient(api_key=None, base_url=..., timeout=10.0)`\n\nCreate a client. Raises `ValueError` if no API key is provided.\n\n### `client.audit(action, contract_address, amount, payload_override=None)`\n\nSynchronous audit. Returns receipt dict:\n\n```json\n{\n  \"xaps_receipt\": true,\n  \"agent_key\": \"...\",\n  \"remaining_balance\": 9.99,\n  \"audit\": {\n    \"status\": \"APPROVED\",\n    \"alpha_defense\": \"...\",\n    \"beta_attack\": \"...\"\n  }\n}\n```\n\n### `await client.audit_async(...)`\n\nAsync variant for agents running on `asyncio`.\n\n### Sink adoption magnet — `audit_then_query` / `query_sink`\n\nAfter a Tollbooth receipt, agents can call the **subsidized Sink** for real structured data (GitHub / HTTP). That is the integration carrot: rails → utility.\n\n```python\nfrom xaps import XapsClient\n\nwith XapsClient() as client:\n    # One shot: fast/swarm audit for query_oracle, then sink\n    result = client.audit_then_query(\n        \"github repo anthropics/anthropic-sdk-python\",\n        oracle_url=\"http://localhost:8766\",  # or XAPS_ORACLE_URL\n    )\n    print(result[\"sink\"][\"data\"])\n\n    # Or reuse an existing receipt\n    receipt = client.audit_auto(\"query_oracle\", \"\", 0.01)\n    data = client.query_sink(\"search github MCP agents\", receipt)\n```\n\nEnv: `XAPS_ORACLE_URL` (sink base), `XAPS_API_URL` + `XAPS_AGENT_KEY` (tollbooth).\n\nMCP: `xaps_audit_then_query`, `xaps_sink_query`, `xaps_sink_health`.\n\n### Exceptions\n\n| Exception | When |\n|-----------|------|\n| `XapsAuthError` | Invalid or missing API key (401) |\n| `XapsPaymentError` | Insufficient prepaid balance (402) |\n| `XapsRateLimitError` | Too many requests (429) |\n| `XapsAPIError` | Other API errors |\n| `XapsRejectedError` | Audit returned `REJECTED` (optional helper) |\n\n---\n\n## Billing\n\n- **$0.01 USD** per successful audit, deducted from prepaid balance\n- Fund your agent key at [xaps.network](https://xaps.network)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/APMC1/xaps-sdk.git\ncd xaps-sdk\npip install -e \".[dev]\"\npytest\n```\n\n> The sovereign node (`xap-sovereign-node`) is private. This public repo contains only the SDK.\n\n---\n\n## Security\n\nYour Xaps Agent Key is a billing identifier, not a cryptographic secret. Do not commit it to version control.\n\n## License\n\nMIT — see [LICENSE](LICENSE).",
  "bytes": 5146,
  "sha": "012cdad9b0be82e443139a9412bbaf4541acc542a4016cc0485377612cee936f",
  "repo_slug": "apmc1/xaps-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_apmc1_xaps_cc436075/readme"
}