Qatom

Qatom Marketplace Skill

Access paywalled API tools from the Qatom marketplace. An agent (sandbox) twin wallet handles payments transparently, so no manual approval steps interrupt your workflow. Providers can register their own APIs and earn per-call revenue automatically.

When to Use

✅ USE this skill when:

• User asks to call a tool from the Qatom marketplace
• A tool requires Qatom wallet payment
• Checking wallet balance or twin info
• Managing your agent (sandbox) twin wallet, funding, or transfers
• Registering as a Qatom provider to earn per-call revenue from your tools
• Managing provider twins, configuring upstream APIs, or updating registered tools

❌ DON'T use this skill when:

• User wants to interact with the payment API directly
• Tool is free and doesn't require a wallet

Connecting

The Qatom MCP server is hosted at https://mcp.m.todaq.net. Connect using any MCP-compatible client with OAuth 2.0 support.

claude.ai (built-in OAuth): Add https://mcp.m.todaq.net as a remote MCP server. The platform handles OAuth redirect and token management automatically.

Claude Desktop: Add the server to your claude_desktop_config.json with OAuth configuration. The desktop client will open your browser for the Qatom OIDC login flow and store the resulting token.

Other MCP clients: Connect to https://mcp.m.todaq.net using standard OAuth 2.0. The authorization server is at https://pay.m.todaq.net. Request the twin scope to receive agent twin credentials alongside your access token.

After connecting, all available Qatom tools appear in the client's tool list automatically.

Auth Flow

1. OAuth redirect — MCP client redirects to Qatom OIDC login at pay.m.todaq.net
2. User authenticates — email + 2FA (TOTP) via the Qatom Flutter app or web
3. Twin auto-provisioning — OIDC returns user identity including twin_hostname and agent_twin_hostname + agent_twin_key. The agent twin is a sandbox wallet auto-provisioned for MCP use. If no agent twin exists, one is created during the first connection.
4. Token introspection — every tool call validates the Bearer token against the OIDC introspection endpoint (result cached for 60 seconds)
5. Session persistence — tokens stored by the MCP client persist across tool calls and sessions, so re-auth is rare
6. MFA skipped for Bearer — agent-initiated calls use a Bearer token (service-to-service). The paywall skips MFA entirely for Bearer calls, so payments execute immediately without manual approval

Available Tools

Wallet Tools

These 4 tools are always available and manage your TODAQ wallet:

Dynamic Tools

Additional tools appear dynamically from the marketplace catalog, fetched from the payment API at connection time (cached for 60 seconds). The agent sees them alongside the static wallet tools in its tool list. Tool names use snake_case (e.g., "Current Weather" registers as current_weather).

Provider Admin Tools

These 8 tools let you create and manage provider twins, register API tools in the marketplace, and earn per-call revenue:

Payment Flow

When an agent calls a marketplace tool, the MCP server orchestrates payment transparently:

1. Token validation — MCP server validates the Bearer token via OIDC introspection. Identifies the user's agent twin for payment.
2. Bearer skips MFA — Bearer token calls bypass MFA entirely. Payment executes immediately.
3. Paywall request — MCP server POSTs to /v4/paywall on the payment API with:
   • amount — the tool's price in USD TDN
   • serviceUrl — the upstream API URL
   • serviceMethod — GET, POST, or PUT
   • additionalParams — tool arguments, present only for POST/PUT tools
4. GET tools — arguments are injected as query string parameters on serviceUrl. No additionalParams field in the paywall body.
5. POST/PUT tools — arguments are packed into the additionalParams field and forwarded as the request body to the upstream API.
6. TODA protocol payment — the payment API calls the agent twin node directly. The agent twin transfers the tool's price to the provider twin via the TODA protocol.
7. Upstream proxy — the provider twin proxies the request to the upstream service URL. The response flows back through the provider twin → payment API → MCP server → agent.
8. Response delivered — the agent receives the upstream API response as the tool call result.

Agent Twin Wallet

Every MCP-authenticated user gets an agent (sandbox) twin, separate from their primary human wallet. This twin is auto-provisioned during the first OAuth connection and is used exclusively for agent-initiated marketplace payments.

Primary vs Sandbox Twin

Fund → Transfer → Spend Lifecycle

1. FUND       Primary wallet gets TDN
                → Use fund_agent_wallet to get the chargeup URL (https://load.m.todaq.net)
                → Add funds through the web UI
                ↓
2. TRANSFER   Move TDN from primary to agent sandbox wallet
                → Use transfer_to_agent_wallet with amount and dq_type
                → Only do this when the agent wallet balance is too low
                ↓
3. SPEND      Agent calls marketplace tools
                → Each call deducts the tool's price from the agent sandbox twin
                → Payment goes to the provider twin automatically

Edge Cases

• Pre-existing sessions — sessions created before agent twin auto-provisioning may have agentTwinHostname as undefined. The MCP server falls back to the primary twinHostname in this case. On the next tool call, the token is re-validated and the agent twin claims are restored automatically.
• Token expiry — OAuth tokens expire after a set duration. When this happens, the MCP client re-authenticates and agent twin claims are refreshed. Wallet balances and twin hostnames remain stable across token refreshes.
• Insufficient sandbox balance — if the agent twin lacks funds for a tool call, the paywall returns an error. The agent should tell the user to add funds and use transfer_to_agent_wallet before retrying.

Become a Qatom Provider

Register your own API endpoints as marketplace tools and earn per-call revenue. Payments flow via TODA protocol from consumer agent twins to your provider twin, with no manual invoicing or settlement.

Just tell your agent: "Help me register as a Qatom provider." The agent will walk you through these steps using the provider admin tools:

Step 1 — Create a Provider Twin

The agent calls create_twin, which provisions a new provider twin to receive payments. Providers can have multiple twins, each linked to a different upstream API or pricing tier. The twin hostname is returned and used in the next steps.

Step 2 — Configure the Twin

The agent calls configure_twin with three parameters:

• hostname — your provider twin hostname (from step 1 or twin_status)
• target_url — the real upstream API URL (must use https)
• price_per_call — minimum USD TDN charged per call

This links your provider twin to the upstream API it will proxy traffic to.

Step 3 — Register the Tool

The agent calls register_tool to list your API in the marketplace. Required parameters:

• twin_hostname — your provider twin hostname
• name — tool name in snake_case (e.g., get_weather_current)
• description — what the tool does, shown to AI agents during discovery
• provider — your display name shown in the marketplace
• price_per_call — price per call in USD TDN (should match configure_twin)
• service_method — GET, POST, or PUT (the HTTP method your upstream API expects)
• input_schema — JSON Schema object describing the parameters consumers must pass

The service URL is derived automatically from your twin hostname.

Step 4 — Test Your Tool

The agent calls test_tool with your tool's ID and sample arguments. This executes the tool through the full paywall exactly as a consumer would experience it. Your agent sandbox twin pays your provider twin for this test call, so you can verify the end-to-end flow including payment.

After testing, your tool is live in the marketplace. Any authenticated MCP agent can discover and call it. The catalog refreshes every 60 seconds, so new tools are visible almost immediately.

Managing Your Tools

Once registered, you can use the provider admin tools to manage your marketplace presence:

• list_my_tools — see all your registered tools with their IDs
• update_tool — change name, description, price, or toggle active/inactive
• deactivate_tool — hide a tool from consumers (visible in the catalog within 60 seconds)
• twin_status — check provider twin balances (the TDN you've earned from tool calls)