TDM AgentPay

Agent Payment Guidance

Public reference package for agent-facing TDM payment flows, recovery guidance, and Session Gas Tank behavior.

Documentation • API Reference • GitHub • X/Twitter

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

TDM CLI [V0.0.2-BETA]
SDK + CLI + MCP
Mode: local-first | Docs: todealmarket.com/docs

---

What is TDM AgentPay?

TDM AgentPay provides runtime guidance for AI agents to:

• Interpret payment responses - Understand payment check results
• Use Session Gas Tank flows - Work with prepaid agent budgets
• Suggest recovery actions - Guide users through tdm fuel, tdm sweep, tdm cashout
• Maintain separation - Keep sweep (recovery) and cashout (seller payout) distinct
• Follow public contracts - Align with documented TDM SDK/CLI behavior

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 across these flows remains broader and includes the CLI and operator paths referenced in this guide.

This repository follows the core TDM product shape:

• primary path: paid API calls, agent tools, route execution, and Session Gas Tank guidance
• secondary path: creator/content unlock flows that sit on top of the same payment surface

In other words, AgentPay is about agent runtime behavior first, not about turning TDM into a generic content marketplace.

Local catalogs and runtime storage can still sit next to AgentPay:

• tdm storage add
• tdm storage sync
• tdm storage watch
• tdm storage publish
• tdm workspace
• tdm status
• tdm workspace status

Those are operator/runtime workflows from tdm-sdk, not part of the core AgentPay authorization contract itself.

For JavaScript integrations, the current public tdm-sdk surface around this contract is intentionally small and explicit:

• makePayable(...) for pricing a route, tool, or action
• createFetchHookClient(...) for live payment-aware hooks
• createAuthorizeClient(...) and createGatewayClients(...) for direct gateway-side payment checks
• createSessionTanksClient(...) and createCheckoutClient(...) for surrounding session and buyer flows

Current recovery-routing notes:

• Solana Jupiter:
  • with JUPITER_API_KEY, the SDK uses 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, the SDK uses https://api.odos.xyz
  • with ODOS_API_KEY, the SDK uses https://enterprise-api.odos.xyz

That routing detail mostly matters for recovery and sweep helpers. AgentPay itself stays focused on payment interpretation and user guidance, not on treasury internals.

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│                    AGENTPAY PUBLIC FLOW                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

    ┌────────────────┐    ┌────────────────┐    ┌────────────────────┐
    │                │    │                │    │                    │
    │  Agent Runtime │───▶│ AgentPay       │───▶│ TDM SDK / Payment  │
    │                │    │ Guidance       │    │ Surface            │
    │                │    │                │    │                    │
    └────────────────┘    └────────────────┘    └────────────────────┘
             │                      │                      │
             │                      │                      │
             ▼                      ▼                      ▼
    ┌────────────────┐    ┌────────────────┐    ┌────────────────────┐
    │ Recovery       │    │ User guidance  │    │ Protected call     │
    │ decision       │    │ such as fuel   │    │ continues after    │
    │                │    │ or retry       │    │ approval           │
    └────────────────┘    └────────────────┘    └────────────────────┘

---

What It Covers

Payment Interpretation POST /authorize responses Payment-required (402) handling Balance checks Authorization IDs Transaction tracking	Session Gas Tank Prepaid budget model Delegated session tokens Session-based spending Multi-agent usage Public payment contract guidance
Recovery Actions tdm connect - One-time setup tdm fuel - Top-up gas tank tdm sweep - Recover dust tdm sweep status - Check progress Separation from cashout	Public Contracts SDK request/response formats CLI command patterns Error code meanings User action recommendations MCP integration guidance Advanced localhost signer mode for custom local integrations Current scoped JS helpers around the same public contract

---

Core Commands

Authentication

# One-time setup
tdm connect

# Advanced manual setup
tdm login --gateway https://tdm.todealmarket.com --api-key apk_xxx

# Advanced session override
tdm login --session-id sess_beta_123

Interactive live runtime commands such as tdm make payable, tdm payout, tdm security, and tdm unlock can now auto-start that one-time setup when the machine is not yet linked to Live TDM. Headless or manual runtimes still use tdm login when browser-wallet setup is not desired.

By default, tdm connect stores the connected wallet locally and prepares the live runtime. In the current multi-wallet MVP, you can connect one wallet per supported network, so the same account can keep a Solana wallet and a Base/EVM wallet available at the same time. TDM then keeps payout wallets network-specific instead of assuming one payout address for every chain. During setup, tdm connect also attempts a safe default payout sync when the inferred chain slot is still empty. It does not overwrite an already saved payout wallet automatically.

If you want connect to stay local-only, use:

tdm connect --no-sync-payout-wallet

If the account protects new payout destinations with TOTP step-up, run:

tdm security totp enroll
tdm security totp verify --method-id <id> --code 123456

Then rerun tdm connect or save the destination explicitly with tdm payout wallets set.

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

Funding

# Top-up Session Gas Tank
tdm fuel --amount 5 --yes

# Fund specific session
tdm fuel --amount 10 --session-id sess_123 --yes

Recovery

# Sweep dust to stablecoin (Solana)
tdm sweep --network solana --resume-burner --deposit-address <solana_address>

# Check sweep status
tdm sweep status

Seller Payouts

# Request cashout (seller only)
tdm cashout

Agent Management

# Create a named vault for an isolated contour
tdm vault create photos --use

# List agents
tdm agent list

# Create agent
tdm agent spawn worker-1 --type DISCRETE --limit 5

# Issue session token for an agent
tdm agent boot worker-1

Optional route policy per vault

If one vault and the agents inside it should only call specific approved destinations, TDM now supports an optional layered allowlist policy:

• project allowlist for shared defaults
• vault allowlist for one isolated contour and its agents

This 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 --scope vault --vault photos --verified
tdm allowlist check https://api.example.com/private/route --vault photos
tdm allowlist list --vault photos

Advanced local signer mode

tdm signer serve

This mode is for advanced users who want to connect their own Python/Node agent scripts to LocalVault without exporting keys.

Important:

• localhost only
• advanced local workflow only
• review local scripts carefully
• keep wallet credentials under your own control

Practical vault sizing

• if operators manage many agents, separate named vaults are usually easier to maintain than one very large vault
• use one vault per business contour or resource group: photos, music, courses, market-bots

Example:

tdm vault create photos --use
tdm agent spawn seller-1 --type DISCRETE --limit 10
tdm agent spawn seller-2 --type DISCRETE --limit 15
tdm signer serve --vault photos --port 41011

---

Payment Flow

sequenceDiagram
    participant Agent as Agent Runtime
    participant SDK as TDM SDK
    participant Payment as TDM Payment Surface
    participant User as User

    Agent->>SDK: Call protected operation
    SDK->>Payment: Check whether the request can proceed
    Payment-->>SDK: Top-up needed
    SDK-->>Agent: Payment required
    Agent->>User: "Suggest: tdm fuel --amount 5"
    User->>User: Run tdm fuel
    User-->>Agent: Ready
    Agent->>SDK: Retry operation
    SDK->>Payment: Check again
    Payment-->>SDK: Access approved
    SDK-->>Agent: Success

Loading

---

Integration Example

For AI Agents (MCP)

# agents/openai.yaml
name: TDM Payment Agent
description: Handles TDM payment flows and recovery

instructions: |
  If setup is missing:
  1. Suggest: tdm connect
  2. Explain: This is the one-time wallet + payment setup

  When you encounter a 402 Payment Required error:
  1. Check the error details for balance and price
  2. Suggest: tdm fuel --amount <needed_amount>
  3. Wait for user confirmation
  4. Retry the operation

  When user asks about dust recovery:
  1. Suggest: tdm sweep --network solana --resume-burner --deposit-address <address>
  2. Explain: This converts leftover tokens to USDC
  3. Monitor: tdm sweep status

  Keep sweep (recovery) and cashout (seller payout) separate!

For SDK Integration

import { createFetchHookClient, makePayable } from 'tdm-sdk';

const hooks = createFetchHookClient({
  baseUrl: 'https://tdm.todealmarket.com',
  apiKey: 'your-api-key'
});

const payableFunction = makePayable(
  async (input: string) => {
    return `Tool result: ${input}`;
  },
  {
    operation: 'agent:tool-call',
    tokenOrUuid: 'user-123',
    hooks
  }
);

try {
  await payableFunction('hello');
} catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    // Agent suggests: tdm fuel --amount 5
  }
}

---

Repository Structure

tdm-agentpay/
├── README.md              ← You are here
├── SKILL.md               ← Agent skill definition
├── LICENSE                ← MIT License
├── agents/
│   └── openai.yaml        ← OpenAI agent configuration
├── references/
│   ├── adaptation-map.md          ← SDK adaptation guide
│   ├── authorize-contract.md      ← /authorize API contract
│   ├── mcp-runtime.md             ← MCP integration guide
│   ├── sdk-sweep-capabilities.md  ← Sweep flow documentation
│   └── vault-scenarios.md         ← Vault usage scenarios
└── scripts/
    ├── fetch_x402_price.mjs       ← Price lookup utility
    └── run_tdm_sweep.mjs          ← Sweep execution script

---

Included Materials

SKILL.md

Agent skill definition for TDM payment flows. Use this to configure AI agents (Claude, GPT-4, etc.) to understand TDM payment patterns.

agents/openai.yaml

OpenAI-compatible agent configuration. Drop this into your MCP server or agent framework.

references/

Detailed documentation on:

• SDK adaptation patterns
• /authorize API contract
• MCP runtime integration
• Sweep capabilities
• Vault scenarios

scripts/

Utility scripts for:

• Fetching 402 payment prices
• Running sweep operations
• Testing payment flows

---

Key Concepts

Session Gas Tank

A prepaid budget for agent workflows. In the current public stack, the practical flow is:

1. User or operator funds the runtime with `tdm fuel`
2. An agent gets a delegated session token through `tdm agent boot <name>`
3. Paid requests go through `POST /authorize`
4. Session spending is enforced by the current Session Gas Tank contract

Sweep vs Cashout

Sweep (Recovery):

• Converts leftover dust to stablecoin
• User-initiated
• Recovers small balances
• Command: tdm sweep

Cashout (Seller Payout):

• Seller requests payout
• Provider-initiated
• Withdraws earned revenue
• Command: tdm cashout

Keep them separate!

---

Security Notes

• No private keys in this repo - This is guidance only
• OS keyring required - CLI stores keys securely
• API keys optional - Some public flows may require authentication
• Session tokens expire - Short-lived by design
• Review local automations carefully - especially when using advanced local signer flows

---

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

• Agent Payment Guide
• SDK Reference
• SDK & CLI Reference
• Session Fuel & Settlement

---

License

MIT License - see LICENSE for details

---

Built by the TDM team

Website • Documentation • GitHub • X/Twitter