TDM Agent Integration Kit

Developer Integration Tools

Reference implementations and copy-paste building blocks for teams that need to add TDM payments into existing projects.

Documentation • API Reference • GitHub • X/Twitter

████████╗ ██████╗  ███╗   ███╗
╚══██╔══╝ ██╔══██╗ ████╗ ████║
   ██║    ██║  ██║ ██╔████╔██║
   ██║    ██║  ██║ ██║╚██╔╝██║
   ██║    ██████╔╝ ██║ ╚═╝ ██║
   ╚═╝    ╚═════╝  ╚═╝     ╚═╝

TDM Integration Kit [V0.1]
CLI + Client + MCP
Mode: local-first | Docs: todealmarket.com/docs

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.

1. 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.

1. 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

1. Smoke test the local signer.

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

1. 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

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