Topics

#ai-agents #api #base #crypto-payments #developer-tools #ethereum #integration #mcp #model-context-protocol #payments #sdk #solana #tdm #typescript #web3 #x402

Language breakdown

TypeScript 100.0%

▸ Files click to expand

README

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

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.

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.

Save the printed signer token and signer URL.

TDMSIGNERTOKEN=...
TDMSIGNERURL=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

Smoke test the local signer.

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

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 JUPITERAPIKEY, 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 ODOSAPIKEY, use https://api.odos.xyz - with ODOSAPIKEY, 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