Tradeos Public Intel Kit MCP Server

TradeOS Public Intelligence Kit

Build source-grounded crypto market Data Intelligence products on top of TradeOS public evidence.

TradeOS is the crypto-market vertical of a broader source-grounded Data Intelligence OS strategy. It is not a trading platform, broker, custodian, managed account service, or hosted execution system. See the TradeOS Business Thesis for the business overview.

This repo gives builders SDKs, MCP tools, a BYOK agent CLI, runnable bots, and the blueprint for the flagship TradeOS app pattern: a private self-hosted Symbol Cockpit.

TradeOS hosts the intelligence API. The cockpit is an individual private-use control plane: it runs on the self-hosted operator's own machine, server, quant workstation, or agent host. It can recommend buy, sell, trim, avoid, watch, or pass decisions from TradeOS evidence plus local rules, while keys, custody, portfolio context, approvals, and execution stay in that operator's environment.

Builders can package or extend this pattern for users to self-host. They should not operate the cockpit as a managed account service, collect customer exchange credentials, custody customer assets, or place orders for customers.

That private self-hosted model is the product advantage. Traders get an actionable agent. Builders get a product they can ship. TradeOS stays the source-grounded intelligence product layer instead of becoming a custodian, broker, or hosted order router.

Think of TradeOS as a crypto market Data Intelligence OS:

• TradeOS supplies the source-backed intelligence layer.
• Builders package that intelligence into briefings, bots, watchlists, dashboards, validation packs, proof pages, and widgets.
• Users and builder apps send structured feedback that improves intelligence quality and provenance.
• Paid TradeOS, x402, or enterprise access starts when a product needs scale, alerts, automation, premium history, private intelligence products, validation APIs, or explicit data rights.

The practical loop is simple:

Use TradeOS free.
Earn Data Intel Credits by improving intelligence quality.
Build and earn on public intelligence.
Pay when you need private intelligence products, scale, alerts, automation, or data rights.

Use the free public kit to prove a workflow. Charge for the packaging around that workflow. Submit feedback with provenance so TradeOS can improve the intelligence layer. Upgrade to paid TradeOS when the product needs production volume, alerts, automation, premium history, private intelligence products, validation APIs, x402 machine access, explicit data rights, or enterprise support.

The flywheel effect is the point: useful TradeOS evidence helps builders ship paid services; paid services create users, usage, feedback, and outcome labels; that feedback improves TradeOS intelligence; better intelligence makes builder products more valuable; successful products then need paid TradeOS depth, x402 access, and enterprise support.

Data Intelligence Services / SKU Map

TradeOS packages intelligence as product layers, not only as raw datasets:

Keep the boundary explicit in builder products. Human DTI credits do not unlock paid API scale, x402 calls, alert delivery, exports, automation, custody, execution, private context, or enterprise data rights. Those are paid, reviewed, or contract-entitled paths.

At A Glance

What This Is

TradeOS sits in the public market-intelligence layer for crypto and on-chain markets. It is one vertical, not the entire Source Intelligence Network strategy. This kit is the builder distribution surface for that Data Intelligence OS. It helps products discover, consume, package, and send feedback on current, source-backed market context inside bots, dashboards, agent workflows, research products, validation systems, and paid communities.

It is an evidence and feedback layer:

• public digest inputs, candidates, watchlists, thesis records, proof lookups, caveats, freshness, source refs, and invalidation notes;
• a public Fusion Signal Cockpit preview that shows redacted symbol-level direction, confidence, freshness, why-fired context, invalidation, and feedback intake without exposing execution fields;
• symbol-cockpit and action-agent patterns for turning evidence into good/bad/ugly verdicts, watchlist recommendations, and bot preflight checks;
• non-executable action intents that carry evidence-backed action context into local review, policy gates, paper execution, or independent executor experiments without becoming orders;
• TypeScript and Python SDKs for apps and services;
• a stdio MCP server for local agent hosts such as Claude Desktop and Cursor;
• a BYOK CLI that can ask Venice AI or another OpenAI-compatible model over TradeOS evidence;
• a market briefing bot that can post to stdout, Discord, or Telegram;
• structured feedback writes with provenance so TradeOS can learn which public intelligence was useful, early, late, thin, or confusing.

It is not a TradeOS-hosted broker, custody product, managed account service, or order router. Builders can wire the open-source kit into local bot, preflight, or execution stacks, but exchange keys, approvals, sizing rules, and custody stay with the self-hosted operator using it for their own account context. If a builder collects customer credentials, controls customer accounts, or runs execution for other people, that builder has created a separate managed trading service outside this kit's supported boundary.

Action intents are the bridge, not the executor. They are marked non_executable, require operator review, and deliberately omit venue, account, size, order type, route, calldata, transaction body, and execute URL fields.

In practical terms:

TradeOS Data Intelligence OS -> intelligence, evidence, data, feedback IDs
Symbol Cockpit -> private local recommendation and decision runtime
Local modules -> feasibility, EA/risk, execution adapters, ops dashboard

Why Builders Use It

• Avoid weak intelligence gaps: reduce wrong-token routing, stale context, unsupported claims, caveat-free recommendations, missed watchlist changes, and outputs that cannot be audited. See Problem Space for exposure anchors that translate weak context into potential dollar impact without promising guaranteed loss prevention.
• Understand the business thesis: TradeOS is the crypto-market Data Intelligence OS vertical. It creates demand with useful public intelligence and monetizes paid depth when workflows need scale, private intelligence, alerts, validation, automation-safe access, or data rights. See TradeOS Business Thesis.
• Ship faster: start with bounded TradeOS evidence instead of building a market data pipeline first.
• Ground agents: give LLMs current evidence, caveats, stable IDs, and source references before they answer.
• Use privacy-enhanced BYOK inference: use Venice AI as the recommended default with e2ee-glm-5-1, an E2EE/TEE-backed upstream model option. Builders can still swap in another OpenAI-compatible provider. Builders that want a marketplace-hosted path can use paid TradeOS AntSeed/x402 SKUs: tradeos-venice-raw-inference for ungrounded model output, or tradeos-venice-intel-router for TradeOS evidence-backed model summaries.
• Earn on top of TradeOS: package TradeOS intelligence into services, workflows, agents, dashboards, vertical apps, or research products customers already understand and will pay to use.
• Show market proof: point prospects to Platform Pulse for live feedback volume, x402 challenge demand, source attribution, and settlement health. Treat x402 challenges as interest signals; only verified/completed payments are revenue.
• Distribute commercially: use the commercial field guides to package TradeOS-backed intelligence on Virtuals ACP, AntSeed, x402 directories, and Agentic.Market-style discovery without publishing private keys or live provider secrets.
• Sell privacy as the feature: ship a cockpit that customers can run on their own box, with their own model key, exchange keys, approval policy, portfolio context, and audit logs.
• Close the loop: send human, agent, or automation feedback back to TradeOS with provenance.
• Scale cleanly: graduate from public reads to paid TradeOS data, x402, or enterprise access when the workflow needs scale, alerts, automation, private intelligence products, or data rights.

What You Can Build

The public kit is the integration and discovery surface. Paid TradeOS starts when customers ask for production-grade volume, automation, history, delivery, private intelligence products, or explicit paid entitlement.

More product detail:

• Problem Space
• Repository Layout
• Integration Keys And URLs
• Getting API Keys And Requesting Scale
• Flagship Symbol Cockpit
• Symbol Cockpit And Action Agent
• Symbol Intelligence Coverage
• Data Intelligence Product Model
• Use Cases
• Monetization Guide
• Earn as a Builder: Commercial Distribution Field Guides
• Builder Revenue Playbook

Flagship: Symbol Cockpit

For a consumer-facing walkthrough of what the cockpit is, how to read it, requirements, dependencies, launch steps, and safety boundaries, see Flagship Symbol Cockpit.

The fastest consumer story is:

Give TradeOS a symbol.
TradeOS returns the good, bad, ugly, verdict, evidence, and an action
recommendation.

Example cockpit language:

VVV: avoid new long.
Good: momentum improved and sector interest remains present.
Bad: fusion agreement degraded and liquidity depth is thin.
Ugly: flow stress is elevated during broader market risk.
Recommendation: avoid a fresh long; if already exposed, consider trim or tighter
risk controls until flow stress normalizes and fusion recovers.
Feedback: useful / wrong / late / missing context.

This cockpit can run privately in the operator's self-hosted deployment. Local watchlists, strategy notes, wallet context, bot rules, and logs stay local unless the operator chooses to send feedback or authenticated context to TradeOS. TradeOS sees the public-intelligence queries and paid scopes the runtime sends.

That is why the cockpit is useful: it is not only a market summary. It is a self-hosted decision layer that can recommend buy, sell, trim, avoid, watch, or pass based on TradeOS evidence plus the operator's local rules. The self-hosted operator owns what happens next.

This is the flagship architecture TradeOS wants builders to copy:

TradeOS public or paid intelligence
        |
        v
Private self-hosted cockpit
        |
        v
Non-executable action intent -> local feasibility gate -> local EA/risk gate
        |
        v
Optional local execution adapter
        |
        v
User-owned wallet, exchange, or broker account

Future open-source modules can add feasibility checks, expected-advantage checks, execution adapters, and a light operations dashboard. The control plane still belongs to the self-hosted operator, not TradeOS.

Five-Minute Paths

Clone and build from source:

git clone git@github.com:agenticsrclab/tradeos-public-intel-kit.git
cd tradeos-public-intel-kit
npm install
npm run build

Run The Symbol Cockpit

The flagship self-hosted app now lives in apps/symbol-cockpit and exposes the web/API/worker runtime described in the cockpit ADR.

export TRADEOS_PUBLIC_INTEL_KEY=<optional-public-intel-app-key>
npm run symbol-cockpit

Open http://127.0.0.1:18100, or run the app-level Compose stack:

cd apps/symbol-cockpit
cp .env.example .env
docker compose up
docker compose --profile risk up
docker compose --profile execution up

CLI and MCP consumers can use the same cockpit contracts:

npm run cli -- cockpit VVV --chain 8453 --mode trader
npm run cli -- preflight VVV --action buy --chain 8453

Run The Market Briefing Bot

This is the first recommended bot to fork: a source-backed market briefing worker for stdout, Discord, or Telegram.

npm run briefing-bot -- brief

That works without a TradeOS account and without an LLM key. It prints a deterministic briefing from live public evidence.

Use Venice AI as the recommended privacy-enhanced BYOK path for a stronger natural-language brief. The kit defaults to e2ee-glm-5-1. Get a key from the Venice AI subscription page:

export VENICE_API_KEY=...
npm run briefing-bot -- brief

Test the post path locally:

TRADEOS_BRIEFING_PLATFORM=stdout npm run briefing-bot -- post

Post to Discord:

export TRADEOS_BRIEFING_PLATFORM=discord
export DISCORD_WEBHOOK_URL=...
export VENICE_API_KEY=...
npm run briefing-bot -- post

More detail: Market Briefing Bot

Ask With The CLI

Fetch evidence without an LLM:

npm run cli -- digest --limit 5
npm run cli -- watchlist --limit 5

Ask a Venice-backed question. Venice is the recommended privacy-enhanced BYOK default for self-hosted workflows, and the kit defaults to e2ee-glm-5-1. Get a key from the Venice AI subscription page:

export VENICE_API_KEY=...
npm run cli -- ask "What changed in crypto market stress?"

Submit feedback:

npm run cli -- feedback \
  --target-id digest_123 \
  --target-type digest \
  --label useful \
  --note "Clear and timely"

Add TradeOS To An MCP Host

Run the local stdio MCP server from this repo:

TRADEOS_API_BASE=https://api.tradeos.tech/v1/public-intel \
npm --workspace @agenticsrclab/tradeos-public-intel-mcp-server run dev

Claude Desktop package-style configuration:

{
  "mcpServers": {
    "tradeos-public-intel": {
      "command": "npx",
      "args": ["-y", "@agenticsrclab/tradeos-public-intel-mcp-server"],
      "env": {
        "TRADEOS_API_BASE": "https://api.tradeos.tech/v1/public-intel",
        "TRADEOS_PUBLIC_INTEL_KEY": "<optional-app-key>",
        "TRADEOS_ACCOUNT_TOKEN": "<optional-account-token-for-watchlists>"
      }
    }
  }
}

The MCP server is local stdio today. The reserved hosted MCP endpoint is:

https://mcp.tradeos.tech/public-intel

It becomes the zero-local-infrastructure path after the hosted HTTP MCP bridge is deployed.

More detail: MCP Tools

Official MCP Registry metadata is prepared for the existing public distribution namespace:

io.github.agenticsrclab/tradeos-public-intel-mcp

The registry entry publishes the local stdio package first. Hosted remote MCP should be added only after https://mcp.tradeos.tech/public-intel is live.

Use The TypeScript SDK

Package install path after NPM publication, or when consuming a local tarball:

npm install @tradeos/public-intel-sdk

import { TradeOSPublicIntelClient } from "@tradeos/public-intel-sdk";

const client = new TradeOSPublicIntelClient();

const digest = await client.getMarketDigest({ limit: 5 });
const snapshot = await client.getTokenWatchlistSnapshot("VVV", {
  mode: "trader",
  chain: "8453",
});

await client.submitDigestFeedback({
  targetType: "digest",
  targetId: "digest_123",
  label: "useful",
  optionalNote: "The caveats were clear.",
});

Use The Python SDK

Package install path after PyPI publication, or when consuming a local build:

pip install tradeos-public-intel

from tradeos_public_intel import TradeOSPublicIntelClient

client = TradeOSPublicIntelClient()
digest = client.get_market_digest(limit=5)
snapshot = client.get_token_watchlist_snapshot("VVV", mode="trader", chain="8453")

Python 3.11 or newer is required.

Try Saved Watchlists

Public token snapshots are keyless. Saved watchlists are user-owned state and require a signed-in TradeOS account bearer token.

export TRADEOS_ACCOUNT_TOKEN=<signed-in-account-token>
export TRADEOS_PUBLIC_INTEL_KEY=<optional-builder-app-key>

import { TradeOSPublicIntelClient } from "@tradeos/public-intel-sdk";

const client = new TradeOSPublicIntelClient({
  accountToken: process.env.TRADEOS_ACCOUNT_TOKEN,
  apiKey: process.env.TRADEOS_PUBLIC_INTEL_KEY,
});

const created = await client.createWatchlist({
  name: "Portfolio risk monitor",
  mode: "investor",
});
const watchlistId = String(created.watchlist.watchlist_id);

await client.addWatchlistItem(watchlistId, { symbol: "VVV", chain: "8453" });
const state = await client.getWatchlistState(watchlistId);

await client.createWatchlistNotificationChannel(watchlistId, {
  channelKind: "in_app",
  target: "tradeos-dashboard",
  minSeverity: "watch",
  digestFrequency: "realtime",
});

await client.triggerWatchlistDeliveries(watchlistId, {
  channelKinds: ["in_app"],
  minSeverity: "watch",
});

The first-party watchlist GUI uses the same API: Watchlist Intelligence

Access Model

Builders and users should not need a TradeOS account just to try the public kit.

Default flow:

No account -> try public reads -> submit feedback anonymously
Builder gets traction -> register app / configure optional public key
User wants saved state -> sign in and connect an account token
Workflow needs premium data -> builder or user pays through x402/API entitlement

TradeOS can issue public-intel app keys for signed-in, email-verified builder accounts. The normal path is the Developer Keys dashboard. The CLI can validate TRADEOS_PUBLIC_INTEL_KEY and can manage app keys when TRADEOS_ACCOUNT_TOKEN is set for trusted automation:

For the short key setup and scale-request path, see Getting API Keys And Requesting Scale.

Public API quota is earned, not unlimited:

Feedback writes are bounded too: app-key writes default to 10/minute and 100/day; anonymous writes default to 5/minute per IP. App keys provide attribution and reputation, not paid entitlement. Data Intel Credits use one common unit with scoped spend rules: human DTI unlocks public dashboard depth, public Ask packs, and read-only Review Lab access; builder feedback affects app reputation and quota confidence. Builders can inspect lifecycle state through /feedback-activity and /app-feedback-status; see Data Intel Credit Loop and Public Intel API. Paid/x402 access is required for private intelligence products, scale, alerts, exports, replay, automation, or data rights.

At launch, each free public read counts as one read unit. Batch, history, export, alert, private-intelligence, and machine-scale surfaces are paid/x402 or entitlement-gated rather than stretched into the free public API.

Free public access is best-effort promotional access: no SLA, no guaranteed availability, no cash value, and it may be rate-limited, changed, paused, degraded, or revoked to protect TradeOS infrastructure. The free public pool is capped separately so paid/x402/contract capacity can be preserved.

GUI Ask TradeOS follows the same conservative loop: 3 anonymous questions, 10 signed-in starter questions for 7 days, and 5-question feedback packs earned with DTI credits.

npm run cli -- auth
npm run cli -- keys create --app-name my-public-intel-app
npm run cli -- keys list
npm run cli -- keys revoke --key-id pubkey_...

Existing app-key secrets are not retrievable. Create or rotate a key, copy the one-time secret, and keep it server-side.

More detail:

• Distribution Setup Guide
• API Keys And Feedback Provenance
• Access And Payments
• Paid Boundaries
• Public Fusion Signal Cockpit Preview

Feature Unlock Loop

More features come from TradeOS service access, not from hidden local code in the SDK, MCP server, CLI, or bot examples.

1. Builder installs the free kit.
2. Builder ships public features using digest, candidates, watchlists, proofs, and feedback writes.
3. End users interact with the builder product and submit structured feedback.
4. TradeOS reconciles stable target IDs into quality signals, app reputation, and scoped credits.
5. Human DTI can unlock temporary public dashboard depth, public Ask packs, or Review Lab passes for the user.
6. When the workflow needs production features, the builder calls paid TradeOS/x402 surfaces.
7. TradeOS checks entitlement or payment and returns premium data.
8. The builder product exposes the paid feature to its customer.

Architecture

Your app / agent / MCP host
        |
        | SDK, CLI, or MCP tools
        v
TradeOS public-intel API
        |
        | bounded public evidence, source refs, caveats, stable IDs
        v
Your product surface
        |
        | optional feedback writes
        v
TradeOS Data Intel Credit loop

Optional BYOK LLM path:

Your app / CLI -> recommended Venice AI BYOK path or another OpenAI-compatible provider
              -> answer grounded in TradeOS public evidence

Optional paid marketplace LLM path:

Your agent -> TradeOS AntSeed/x402 `tradeos-venice-raw-inference`
           -> raw Venice model output, not TradeOS-grounded

Your agent -> TradeOS AntSeed/x402 `tradeos-venice-intel-router`
           -> TradeOS SKU routing + evidence packet + Venice explanation layer

The hosted TradeOS Venice SKUs use e2ee-glm-5-1 by default. Market them as privacy-enhanced Venice-backed inference. Do not claim TradeOS is blind to prompts or evidence packets in the hosted route; TradeOS still authenticates, meters, routes, and assembles evidence before forwarding to Venice.

More detail: Architecture

Repository Layout

• packages/sdk-js: TypeScript SDK.
• packages/sdk-python: Python SDK.
• packages/mcp-server: stdio MCP server for local agent hosts.
• apps/tradeos-agent-cli: BYOK CLI for evidence reads, Venice-backed asks, and feedback writes.
• apps/market-briefing-bot: Discord, Telegram, and stdout market briefing bot powered by TradeOS public evidence.
• examples: Claude Desktop and Cursor MCP configuration examples.
• docs: architecture, setup, use cases, monetization, API reference, MCP tools, feedback loop, access and payments, paid boundaries, safety boundaries, public Fusion preview, production readiness, and consumer E2E notes.

Start with the docs index.

Public API

Default production base URL:

https://api.tradeos.tech/v1/public-intel

Useful public reads:

GET /sources/health
GET /watchlist-capabilities
GET /tokens/{token_ref}/watchlist-snapshot
GET /digest-inputs
GET /candidates
GET /thesis-watchlist
GET /thesis-feedback
GET /proofs/{public_claim_id}

Feedback writes:

POST /conversions       digest/evidence feedback
POST /claim-outcomes    public claim feedback
POST /thesis-outcomes   thesis feedback
POST /watchlists/{watchlist_id}/feedback

Builder access:

POST /api-keys          create an attributed builder key
POST /quota-requests    request reviewed public quota or paid evaluation

More detail: Public API

Contribute Apps, Tools, And Services

This kit is meant to be a builder surface, not just a client library. TradeOS welcomes contributions that help developers turn public intelligence into useful products and send structured feedback back to the intelligence loop.

Good contribution lanes:

The best contributions are small, runnable, and commercially useful: they help a builder ship a workflow, keep secrets server-side, respect the safety boundary, and make the TradeOS feedback loop stronger.

Start here: Contributing

Safety Boundary

This kit can produce trade/action recommendation cards, but it does not place trades from TradeOS infrastructure, accept exchange credentials, custody assets, expose raw private telemetry, or guarantee that a token is safe. Execution, allocation, approvals, and exchange keys belong in the individual operator's private self-hosted environment.

See Safety Boundaries.

Verified Consumer Flow

Before publish, this kit was tested from fresh tarball installs as an external consumer:

• CLI digest read.
• CLI Venice-backed ask.
• CLI feedback write.
• TypeScript SDK read and feedback write.
• stdio MCP initialize, tool listing, digest read, and feedback write.
• Python SDK read and feedback write.
• account signup, VVV watchlist state/events, in-app delivery audit, unverified-email skip audit, watchlist feedback, and archive against the public hosts.

See Consumer E2E.

Before making the repository public, run the publish gate in Production Readiness.

Explore TradeOS

• TradeOS app
• TradeOS Public Intelligence Kit on GitHub
• Live market intelligence
• Watchlist Intelligence
• Ask TradeOS
• Developer Keys
• Review Lab
• How TradeOS Works
• Public docs
• Public machine-readable docs
• x402 discovery
• x402 listings