---

What is TDM Agent Integration Kit?

This kit gives developers three public integration surfaces they can use from almost any stack:

• tdm CLI for shellable flows
• local signer HTTP on 127.0.0.1 for advanced local agents
• MCP for agent runtimes that already speak MCP

The public GitHub repo for tdm-sdk shows the open contract-facing SDK surface: https://github.com/ToDealMarket/tdm-sdk

The current tdm-sdk npm beta used throughout this kit remains broader and includes the CLI and operator flows referenced below.

It also now covers the local catalog and runtime-ops path:

• named storage roots
• folder import and sync
• watch loops for long-lived operator machines
• local or tunnel publish flows for stored assets and folders
• optional tdm workspace orchestration for reusable vault + storage + agent contours
• tdm status, tdm where, and tdm workspace status for the main operator view

What is inside

• client: tiny @tdm/client wrapper for CLI + local signer
• examples: copy-paste recipes for common stacks
• mcp-server: standalone @tdm/mcp-server reference package

---

Build An Integration In 10 Minutes

1. Install and connect TDM.

npm install -g tdm-sdk
tdm connect
tdm status

tdm connect now stores your primary wallet locally. In the current multi-wallet MVP, you can keep one wallet per supported network for local signing and seller payouts, and tdm connect also attempts a safe default payout sync for the same network when that payout slot is still empty.

• it does not overwrite an already saved payout wallet automatically
• use tdm connect --no-sync-payout-wallet if you want a local-only connect
• if your account requires step-up for a new payout destination, run tdm security totp enroll, then tdm security totp verify, and rerun tdm connect or use tdm payout wallets set
• you can save payout wallets per network, so for example one wallet can be used for Solana and another for Base/EVM without replacing the other

tdm security totp enroll now opens a local setup page with a QR by default. Use --no-browser when you want terminal-only setup with the secret or otpauth:// URL.

If an operator jumps straight into a live command such as tdm make payable, tdm payout request, or tdm unlock, the interactive CLI can now auto-start the same Live TDM setup instead of leaving the runtime half-configured.

Vault and agent binding

Agent isolation is vault-first, not fuzzy session magic:

• the selected vault comes from --vault <name>, or TDM_VAULT, or the active vault marker written by tdm vault use
• each named vault has its own credentials file under ~/.tdm/vaults/<name>/credentials.json
• keyring refs are namespaced per vault, so the same agent name in two vaults does not collide
• agents are stored under that vault's local credentials.agents map and are registered live from that same vault contour
• MCP follows the same resolution order, so it reads one explicit vault context instead of merging multiple vaults together

In practice, one agent belongs to one selected vault at a time. Workspaces can attach agents for orchestration, but they do not replace vault ownership.

2. Start the local signer if your integration needs local signatures.

tdm signer serve

By default, TDM now asks the OS for a random free localhost port and prints the exact base URL plus signer token.

3. Save the printed signer token and signer URL.

TDM_SIGNER_TOKEN=...
TDM_SIGNER_URL=http://127.0.0.1:<printed-port>

If you want a fixed port for local development examples, start it explicitly with one:

tdm signer serve --port 41001

4. Smoke test the local signer.

curl http://127.0.0.1:<printed-port>/v1/health

5. Pick a recipe from examples or use @tdm/client.

---

Local catalogs and runtime workspaces

If the operator wants to keep files on their own machine or server instead of moving everything into external hosting first, the public CLI path is now:

tdm storage add media ./seller-storage --use
tdm storage import-dir ./products/docs --storage media
tdm storage publish ./products/docs --storage media --mode tunnel
tdm workspace create seller-lab --storage media --use
tdm workspace attach-agent seller-lab worker-1
tdm status
tdm workspace status
tdm make payable --asset <asset-id> --storage media --price 0.05

That flow keeps the catalog local-first while still allowing public delivery through a tunnel or other operator-managed hostname.

Optional runtime route policy

If an integration needs a stricter outbound policy, TDM now supports an optional layered allowlist:

• project allowlist for shared defaults across the repo
• vault allowlist for one isolated contour and the agents inside it

This layer is optional. If you do not configure it, the runtime keeps the broader flexible behavior instead of blocking routes by default.

tdm trust verify domain --target api.example.com --resource res_demo123
tdm allowlist add api.example.com
tdm allowlist add api.example.com --scope vault --vault seller-bot --verified
tdm allowlist check https://api.example.com/private/route --vault seller-bot
tdm allowlist list --vault seller-bot

---

How to use this kit

Start with the smallest surface that solves the task:

• use CLI when the host project can shell out and just needs payment setup or payable resource registration
• use @tdm/client when you want one JavaScript entrypoint for CLI plus local signer access
• use chargeFetchHandler(...), chargeExpressHandler(...), tdm-sdk/authorize, tdm-sdk/checkout, tdm-sdk/session-tanks, or createGatewayClients(...) when you want a direct live gateway integration in JavaScript without building a fake monolithic SDK wrapper
• use Local signer HTTP when the host project is Python, Go, Ruby, or mixed-stack
• use MCP when the runtime already speaks MCP and only needs session checks or payment guidance

Treat the examples as reference implementations, not as plugins that must be installed exactly as-is.

Current routing notes

For recovery and sweep-style flows, the current public SDK behavior is:

• Solana Jupiter:
  • with JUPITER_API_KEY, use https://api.jup.ag/swap/v1
  • without a key, the SDK keeps a compatibility fallback to https://lite-api.jup.ag/swap/v1
• Base Odos:
  • without ODOS_API_KEY, use https://api.odos.xyz
  • with ODOS_API_KEY, use https://enterprise-api.odos.xyz

These details matter for builders wiring local recovery helpers or copying SDK examples into their own stack.

---

Who this kit is for

This kit is for:

• coding agents integrating TDM into existing apps
• developers adding paid access to APIs, routes, tools, bots, and local workflows
• teams that want a practical starting point instead of building every integration piece from scratch

This kit is not the buyer-facing checkout product.

End buyers should not need to install npm or run local TDM tooling just to pay. For broad buyer adoption, the right path is a hosted or embedded checkout surface on top of TDM, while this kit remains the integration layer for builders.

---

Public discovery and checkout entry points

Public payable resources can also be exposed through shareable discovery and checkout entry points:

• x402/Bazaar-style listing feed: GET /api/v1/bridge/x402/resources
• MPP-style service feed: GET /api/v1/bridge/mpp/services
• MPP-oriented discovery text feed: GET /api/v1/bridge/mpp/llms.txt
• buyer entry redirect: GET /api/v1/bridge/buy/:resourceId
• programmatic checkout-session entry: POST /api/v1/bridge/purchase

These endpoints do not replace TDM checkout or authorization. They help external tools, directories, and lightweight clients find a resource and enter the normal purchase flow.

---

Choose The Right Surface

CLI Best when: your stack can run shell commands you want the quickest possible integration you need connect, make payable, balance, payout request, or unlock	Local signer HTTP Best when: you need local signing without exporting keys your app already knows how to build payloads you want language-agnostic access from Python, Go, Ruby, Node, or local tools
MCP Best when: your runtime already supports MCP you only need local TDM session-state hints you want a narrow agent helper instead of a general-purpose signer	Integration Examples Available in examples: Express.js paywall Next.js gated content Python FastAPI Telegram bot

---

Important boundaries

• @tdm/client is intentionally thin; it keeps the public integration path explicit
• @tdm/client is for CLI plus local signer workflows; it is not the new live gateway facade layer
• local signer mode is for advanced users and custom integrations
• review what your app signs and keep wallet credentials in your local environment
• for paid files, prefer short-lived links or inline payloads over permanent public redirects

---

Suggested rollout

• use examples/express-paywall or examples/nextjs-gated for agent or API paths
• use examples/python-fastapi when the host stack is Python
• use examples/telegram-bot for bot-style creator or agent delivery

---

Repository Structure

TDM-Agent-Integration-Kit/
├── README.md              ← You are here
├── LICENSE                ← MIT License
├── client/
│   ├── src/               ← Client source code
│   ├── dist/              ← Built distribution
│   ├── test/              ← Client tests
│   ├── package.json       ← Client package config
│   ├── tsconfig.json      ← TypeScript config
│   └── README.md          ← Client documentation
├── mcp-server/
│   ├── src/               ← MCP server source
│   ├── dist/              ← Built distribution
│   ├── test/              ← MCP server tests
│   ├── package.json       ← MCP package config
│   ├── tsconfig.json      ← TypeScript config
│   └── README.md          ← MCP documentation
└── examples/
    ├── express-paywall/   ← Express.js integration
    ├── nextjs-gated/      ← Next.js integration
    ├── python-fastapi/    ← Python FastAPI integration
    ├── telegram-bot/      ← Telegram bot integration
    └── README.md          ← Examples overview

---

Security Notes

• No private keys in this repo - This is guidance only
• OS keyring required - CLI stores keys securely
• Local signer is localhost-only - Advanced users only
• Review local automations carefully - especially when using advanced local signer flows
• Keep wallet credentials under your control - Never export private keys

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Update documentation
4. Add examples
5. Submit a pull request

---

Documentation

• TDM Documentation
• SDK Reference
• Integration Guide
• Agent Payment Guide

---

License

MIT License - see LICENSE for details

---