Content
<div align="center">
# TDM Integration Kit
<img src="https://img.shields.io/badge/TDM-Integration%20Kit-ff69b4?style=for-the-badge&logo=puzzle&logoColor=white" alt="TDM Integration Kit" />
**Developer Integration Tools for TDM DaOS**
[](./LICENSE)
[](https://modelcontextprotocol.io/)
[](https://github.com/ToDealMarket/tdm-integration-kit/stargazers)
[](https://www.typescriptlang.org/)
*Reference implementations and copy-paste building blocks for teams integrating with TDM DaOS contracts, payments, and agent runtime surfaces.*
[Documentation](https://todealmarket.com/docs) • [API Reference](https://todealmarket.com/docs/api) • [GitHub](https://github.com/todealmarket) • [X/Twitter](https://x.com/todealmarket)
<pre align="center">
████████╗ ██████╗ ███╗ ███╗
╚══██╔══╝ ██╔══██╗ ████╗ ████║
██║ ██║ ██║ ██╔████╔██║
██║ ██║ ██║ ██║╚██╔╝██║
██║ ██████╔╝ ██║ ╚═╝ ██║
╚═╝ ╚═════╝ ╚═╝ ╚═╝
TDM Integration Kit [V0.1.0]
DaOS Contracts + Client + MCP
Mode: local-first | Docs: todealmarket.com/docs
</pre>
</div>
---
## What is this?
Reference implementations and copy-paste building blocks for integrating with **TDM DaOS** (Decentralized Agent Operating System). This kit provides:
- A thin **JavaScript client** (`@tdm/client`) for CLI + local signer workflows
- A standalone **MCP server** (`@tdm/mcp-server`) with 19 tools for agent runtimes
- **Examples** for Express, Next.js, FastAPI, and Telegram bots
The canonical TDM SDK (`npm install -g tdm-sdk`) is the full operator surface. This kit documents the integration contracts exposed by that SDK and provides reference building blocks for advanced integrations.
---
## Quick Start
```bash
npm install -g tdm-sdk
tdm connect
tdm status
```
Pick a recipe from [`examples`](./examples) or use [`@tdm/client`](./client).
---
## What's Inside
| Component | Package | Purpose |
|-----------|---------|---------|
| [`mcp-server/`](./mcp-server) | `@tdm/mcp-server` | MCP stdio server with 19 tools for agent runtimes |
| [`client/`](./client) | `@tdm/client` | Thin JS wrapper for CLI + local signer HTTP |
| [`examples/`](./examples) | -- | Copy-paste integration recipes |
---
## MCP Server (`@tdm/mcp-server`)
A standalone MCP stdio server exposing TDM session state, capabilities, plugins, memory, and budget context to agent runtimes.
### Available Tools
| Tool | Description |
|------|-------------|
| `tdm_get_session_state` | Read local wallet, balance, setup hints |
| `tdm_capability_list` | List machine-readable capabilities |
| `tdm_agent_status` | Agent readiness, runtime, storage, gateway status |
| `tdm_agent_readiness` | Short agent checklist for handoff |
| `tdm_agent_runtime_report` | Wide bounded runtime surface |
| `tdm_plugin_list` | List registered contour plugins |
| `tdm_plugin_get` | Read single plugin card |
| `tdm_hub_catalog_list` | List Hub catalog entries (filterable, paginated) |
| `tdm_hub_install_plan` | Read Hub install plan (governance-aware) |
| `tdm_contour_run_list` | List recent contour run metadata |
| `tdm_contour_run_latest` | Read latest contour run summary |
| `tdm_checkpoint_list` | List checkpoint metadata |
| `tdm_budget_status` | Read budget/scope status |
| `tdm_memory_health` | Read TDM Agent Memory health |
| `tdm_memory_recall` | Search scoped memory records |
| `tdm_memory_save` | Save scoped memory record (with redaction) |
| `tdm_memory_slots` | List pinned memory slots |
| `tdm_memory_slot_update` | Create/replace pinned memory slot |
| `tdm_memory_forget` | Tombstone memory record with audit |
Setup via CLI:
```bash
tdm mcp # writes .mcp.json pointing to tdm mcp serve
```
---
## Examples
| Example | Stack | What It Demonstrates |
|---------|-------|---------------------|
| [`express-paywall/`](./examples/express-paywall) | Express.js | `chargeExpressHandler()` with $0.05 paywall |
| [`nextjs-gated/`](./examples/nextjs-gated) | Next.js App Router | `chargeFetchHandler()` in POST route handler |
| [`python-fastapi/`](./examples/python-fastapi) | Python / FastAPI | Local signer HTTP integration from Python |
| [`telegram-bot/`](./examples/telegram-bot) | Python | Subprocess `tdm make payable` for bot workflows |
---
## Choosing the Right Surface
| Surface | When to Use |
|---------|-------------|
| **CLI** | Your stack can shell out; need `connect`, `make payable`, `balance`, `payout`, `unlock` |
| **Local signer HTTP** | Language-agnostic signing from Python, Go, Ruby, Node; no key export |
| **MCP** | Runtime speaks MCP; need session state, plugins, memory, budget context |
| **SDK direct** | `chargeFetchHandler()`, `chargeExpressHandler()`, `createGatewayClients()` for live gateway in JS |
---
## SDK Integration Surface
For JavaScript/TypeScript integrations, the public `tdm-sdk` provides:
| Export | Purpose |
|--------|---------|
| `makePayable()` | Wrap any async function with payment hooks |
| `chargeFetchHandler()` | Protect a fetch handler (Cloudflare Workers, Deno) |
| `chargeExpressHandler()` | Protect an Express route |
| `chargeHonoHandler()` | Protect a Hono route |
| `createFetchHookClient()` | Live gateway authorize + telemetry hooks |
| `createGatewayClients()` | Composed client: authorize + sessionTanks + checkout |
| `createAuthorizeClient()` | Direct payment authorization |
| `createSessionTanksClient()` | Session gas tank management |
| `createCheckoutClient()` | Buyer-facing checkout flows |
---
## Vault and Agent Binding
Agent isolation is vault-first:
- `--vault <name>` or `TDM_VAULT` selects the active vault
- Each vault has its own credentials under `~/.tdm/vaults/<name>/`
- Agents are scoped to one vault at a time
- MCP follows the same resolution order
```bash
tdm vault create photos --use
tdm agent spawn worker-1 --type DISCRETE --limit 5
tdm agent boot worker-1
```
---
## Optional Route Policy
Layered allowlist for stricter outbound control:
```bash
tdm trust verify domain --target api.example.com --resource res_demo123
tdm allowlist add api.example.com --scope vault --vault seller-bot --verified
tdm allowlist check https://api.example.com/private/route --vault seller-bot
```
---
## Security Notes
- **No private keys in this repo** -- this is reference code and guidance
- **OS keyring required** -- CLI stores keys securely
- **Local signer is localhost-only** -- advanced users only
- **Review local automations carefully** -- especially when using advanced signer flows
- **Keep wallet credentials under your control** -- never export private keys
---
## Contributing
1. Fork the repository
2. Create a feature branch
3. Update documentation
4. Add examples
5. Submit a pull request
---
## Documentation
- [TDM Documentation](https://todealmarket.com/docs)
- [SDK Reference](https://todealmarket.com/docs/api/sdk)
- [Integration Guide](https://todealmarket.com/docs/integration-kit)
- [Agent Payment Guide](https://todealmarket.com/docs/agent-pay)
---
## License
MIT License - see [LICENSE](./LICENSE) for details
---
<div align="center">
**Built by the TDM team**
[Website](https://todealmarket.com) • [Documentation](https://todealmarket.com/docs) • [GitHub](https://github.com/todealmarket) • [X/Twitter](https://x.com/todealmarket)
</div>
