Skip to content
TrueNorth Developers

Use-case gallery

Market data and analysis examples, with API requests and responses.

36 catalogue entriesCrypto · US equities · FX · macromedian 188 ms response — measured across 56 live callsREST + MCP

Market context

Market overview

US spot ETF flows, Bitcoin cycle indicators, earnings, economic releases, and ranked news.

US buy / sell pressure

Whether US spot venues are trading above or below the global price.

loading

US spot ETF flows

How much money entered or left the US spot ETFs each day.

loading

Fear & greed

Where sentiment sits on the 0-100 index today, and where it sat before.

loading

Cycle position

How far market value sits above or below realised value, as an MVRV z-score.

loading

Earnings calendar

Which companies report in a date window, and what consensus expects.

sample

Economic calendar

Which macro releases land in a date window, and what the prints came in at.

sample

News feed and top movers

Two calls: one returns ranked stories with an importance score, the other a momentum leaderboard.

Your home / overview
1

News strip

2

Top movers

One endpoint serves both a market feed and a topic feed: pass a token id for the first, free text for the second. Crypto coverage is deeper than equities today, so for stocks the free-text query is usually the better route. 

const TN = "https://tn-api.truenorth.xyz";

const news = await fetch(TN + "/api/agent-tools/call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    toolName: "event_v2",
    arguments: { token_address: "bitcoin", limit: 6 }
  })
}).then(r => r.json());

news.data.result.results.forEach(story => {
  story.title;              // headline
  story.publisher;          // source
  story.published_at;       // epoch milliseconds
  story.event_type;         // "sec_filing", "earnings", ...
  story.final_rank_score;   // 0-100 importance
});

// The movers rail is the same scanner the markets page uses,
// read as a one-line ticker: symbol + 7d move.
const scan = await fetch(TN + "/api/agent-tools/call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    toolName: "performance_scanner",
    arguments: { top_n: 8 }
  })
}).then(r => r.json());

scan.data.result.leaderboard.forEach(row => {
  row.ticker;        // "LINKUSDT"
  row.momentum_7d;   // 11.7
});

Asset discovery

Asset screening

Compare ranked signals, seven-day momentum, and performance against a selected benchmark.

Your markets page
1

Rank, signal, momentum and benchmark-relative performance come from one scanner call; price is not among the fields it returns. Symbol logos join from the token registry (GET /api/tokens/all) on each row’s token id. 

const scan = await fetch(TN + "/api/agent-tools/call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    toolName: "performance_scanner",
    arguments: { top_n: 8 }
  })
}).then(r => r.json());

scan.data.result.leaderboard.forEach(row => {
  row.rank;              // 1
  row.ticker;            // "LINKUSDT"
  row.signal;            // "BUY" | "HOLD" | "WEAK" | ...
  row.momentum_7d;       // 8.19
  row.rs_vs_benchmark;   // 6.60 vs the benchmark
});

// Tune universe, lookback and benchmark per request:
//   { top_n: 8, lookback_days: 7, benchmark: "bitcoin" }

Symbol deep dive

Asset analysis

Review technical analysis and news for a selected asset. Crypto tools cover options, derivatives, liquidation risk, and positioning. Equity tools cover earnings, fundamentals, analyst estimates, and ownership.

Crypto
US equity
Any symbol

Any symbol resolves through resolve_asset to a canonical token_address, its display_symbol and an asset_class — which is what says whether the crypto endpoints or the US-equity ones cover it.

1

Key levels

Where price has repeatedly stalled or turned, measured against the reference price.

BTC
sample
2

Options positioning

What options traders pay for upside versus downside, and where open interest sits.

BTC
sample
3

Derivatives

What it costs to hold a perpetual, how crowded the book is, and where leverage gets liquidated.

BTC
sample
4

News

Which stories about one asset ranked highest, and what kind of event each was.

BTC
5

Position risk

The modelled odds that a leveraged position reaches its liquidation price.

BTC
6

Hyperliquid smart money

How large, historically profitable wallets are positioned right now.

BTC
sample
7

Prediction markets

The odds a betting market quotes on price levels, and how much money backs them.

BTC
Polymarket sample

Indicator matrix

What the standard indicator set reads on three timeframes at once.

Bitcoin
sample

Each facet is a standalone call. Ship one or all of them. The whole surface is 36 endpoints, reachable over REST or MCP.

Integrate

How to integrate

Resolve an asset identifier, make an HTTP request, and select the required analysis.

  1. 1

    Resolve each symbol once

    Turn a user-facing ticker into the canonical token_address at listing time or on first search, and store it beside your own instrument row. Every later call is then a direct lookup, not a lookup plus a resolve. 

    const TN = "https://tn-api.truenorth.xyz";

const res = await fetch(TN + "/api/agent-tools/call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    toolName: "resolve_asset",
    arguments: { query: "NVDA" }
  })
}).then(r => r.json());

res.data.result.token_address;   // "stock_nvda" - store this
res.data.result.asset_class;     // "stock"
    • result.token_addressthe resolved asset identifier; check each tool for its required input
    • result.asset_classcrypto / stock / commodity / fx
    • result.display_symbol / display_namewhat to show the user
    resolve_assetlive
    Try:
  2. 2

    Call the endpoints with the canonical id

    One POST to /api/agent-tools/call with a tool name and arguments, or a plain GET where one exists. Calls run straight from the browser, so a widget can ship without touching your backend. 

    // One plain GET, where one exists:
const fg = await fetch(TN + "/api/fear-greed?limit=30")
  .then(r => r.json());
fg.data.items;   // [{ date, value, btcPrice }]

// One tool call, for everything else - the canonical id
// from step 1 is the only argument that changes:
const ta = await fetch(TN + "/api/agent-tools/call", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    toolName: "technical_analysis",
    arguments: { token_address: "stock_nvda" }
  })
}).then(r => r.json());

ta.success;        // check before reading data
ta.data.result;    // the tool's own response
    { "data": <the result>, "success": true, "message": null, "code": null, "failed": false }

    Every response shares that envelope. Check success before trusting data; on failure message carries a readable reason.

  3. 3

    Choose timeframes and sections

    Two arguments are the extension points: timeframe sweeps one technical response across the horizons your users switch between, and sections adds the heavier derivatives surfaces on request. 

    // Same endpoint, one argument, a different surface:
{ toolName: "technical_analysis",
  arguments: { token_address: "bitcoin", timeframe: "4h" } }

{ toolName: "derivatives_analysis",
  arguments: { token_address: "bitcoin",
               sections: ["funding", "open_interest",
                          "liquidations", "orderflow"] } }

// Or connect a coding agent over MCP instead of raw HTTP
// (this one needs a key, self-served in the app):
//   https://mcp.true-north.xyz/mcp?token=<your-key>
    • timeframe1h, 4h, 1d; one call per horizon
    • sectionsfunding, open_interest, liquidations, orderflow
    • MCPRead-only tool access through MCP. Requires a key.

    Request a heavier section when a user opens that surface, not on first load.

Reference

Resources

API documentation, tool definitions, and request examples.

API reference Parameters, responses, and request testing. endpoints.json The index: id, method, path and description per endpoint. openapi.json OpenAPI 3.1 schemas and examples.

↑ ↓ Navigate↵ OpenEsc Close