Nut Ecosystem API

Knowledge-base chat, market context and private documentation triage

Integration contract

Reviewed 15 October 2026 against the KB service. Examples below show response shapes, not live prices or usage.

Chat returns one completed JSON response; it does not stream. Treat its HTML content and all external material as untrusted. Sanitize before inserting it into a page. The assistant cannot sign transactions or run commands.

Send JSON bodies with Content-Type: application/json. Request bodies are limited to 160,000 bytes. Browser API origins currently allowed are https://kb.thetanuts.finance and https://thetanuts.finance; other browser origins receive 403. CORS is not authentication.

For contract integration, use the OptionBook callback and event guide and developer hub. A generated answer is not a transaction simulation or a fillable quote.

API endpoints

POST /api/chat Ask a question

Request

FieldFormatMeaning
queryRequired stringNon-empty question, up to 8,000 characters.
conversationOptional arrayUp to 40 prior messages. Each contains only role (user or assistant) and string content. Each content is limited to 16,000 characters; combined history is limited to 80,000 characters.
{
  "query": "What does OptionBook mean?",
  "conversation": []
}

Send prior history yourself. Chat does not load a saved conversation from a conversation ID. System, developer and tool roles, tool-call metadata and other message fields are rejected.

Response

{
  "content": "<p>OptionBook uses presigned maker orders.</p>",
  "tool_calls": null,
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 20,
    "total_tokens": 120
  },
  "timings": {
    "request_start": 0,
    "spending_check": 0,
    "data_loading": 0,
    "llm_calls": [],
    "tool_execution": [],
    "total": 0
  },
  "provider": "Groq",
  "model": "qwen/qwen3.8-27b"
}

content is HTML text. tool_calls is null or an array of research-tool calls; it can be empty when only private feedback was considered. usage and timings are diagnostic metadata, not a billing receipt. Usage describes the final answer call; separate tool/review calls are also accounted by the service.

The browser waits up to 65 seconds. Empty final answers and unavailable providers produce a retryable failure rather than a successful blank reply.

GET /api/feedback Read the feedback count

Returns only the number of active private feedback records. There is no public list or detail response, including when query parameters are supplied.

{
  "count": 3
}

Genuine documentation gaps can be proposed automatically, screened for injection/refusal reports and reviewed before storage. Feedback is untrusted material for human triage. The chat model never reads queued entries, and the public page displays only the count. Injection attempts, refusals, input bugs and temporary outages are not documentation-gap submissions.

POST and DELETE are not public operations on this route. A proposal does not change the knowledge document.

GET /api/market-data Read aggregated market context

Returns collection timestamps, per-asset analytics, signed-order context and collection errors. Individual failed sources may be absent even when the response is HTTP 200. Check errors, each source timestamp and measurement availability.

{
  "timestamp": "2026-10-15T00:00:00.000Z",
  "date": "Thursday, October 15, 2026",
  "time": "12:00 AM UTC",
  "analytics": {},
  "orderBook": {},
  "errors": [
    "BTC analytics: unavailable",
    "ETH analytics: unavailable",
    "Order Book: unavailable"
  ]
}

When present, analytics.BTC and analytics.ETH include spotPrice, keyLevels, sortedKeyLevels, putCallRatios, omittedLevels, schemaVersion, timestamp and asOfMs. orderBook contains orders and totalOrders. A collection timestamp does not make every underlying measurement current. See the analytics reference.

POST /api/news Read news by public topic

Supply one to three queries, each up to 300 characters. Both {"queries": [...]} and an array body are accepted; query entries can be strings or objects containing q.

{
  "queries": [
    "Thetanuts Finance"
  ]
}

Response

[
  {
    "query": "Thetanuts Finance",
    "news": [],
    "searchParameters": null,
    "fetched_at": "2026-10-15T00:00:00.000Z",
    "error": null
  }
]

Each result has its own error state. News text and links are external content; an article is not an instruction to the application or a verified protocol claim.

GET /api/options Read options grouped by expiry
FieldFormatMeaning
minPriceNumber; default 0.01Lower premium filter bound.
maxPriceNumber; default 0.20Upper bound. Require 0 ≤ minPrice ≤ maxPrice ≤ 1.
otmOnlyBoolean; default falseUse true to keep only out-of-the-money options.
bps, nopad, markBoolean; default falseAccepted and echoed in filters. This JSON response still returns numeric bid, ask and mark fields; do not assume these flags convert its price units.
{
  "expiryGroups": {
    "BTC-16OCT26": {
      "underlyingPrice": 83000,
      "options": [
        {
          "strike": "85000",
          "type": "C",
          "strikeType": "85000-C",
          "bid": 0.02,
          "ask": 0.024,
          "mark": 0.022
        }
      ]
    }
  },
  "timestamp": "2026-10-15T00:00:00.000Z",
  "filters": {
    "minPrice": 0.01,
    "maxPrice": 0.2,
    "bps": false,
    "nopad": false,
    "mark": false,
    "otmOnly": false
  }
}

Premiums are denominated in the underlying asset. In this response mark is the rounded bid/ask midpoint, not a guarantee of the exchange mark or an executable quote. timestamp is the formatting time. An unavailable source can return an error object with HTTP 200; check it before using the data. See the pricing reference.

GET /api/spending Read shared daily usage
{
  "spent": 0.75,
  "limit": 25,
  "remaining": 24.25,
  "percentUsed": 3
}

Dollar amounts are the service's estimated model usage for the shared UTC day. The current threshold is $25. The estimate uses configured token rates and eventually consistent accounting; it is not an atomic hard spending cap or a per-user allowance.

POST /api/conversation/save Create a shared snapshot

Body: conversation, using the same message validation as chat history. Every save creates a new server-generated ID; supplying an existing conversationId does not overwrite that snapshot.

{
  "conversation": [
    {
      "role": "user",
      "content": "What is OptionBook?"
    }
  ]
}

Response

{
  "success": true,
  "conversationId": "conv_1792022400000_0123456789abcdef0123456789abcdef",
  "shareKey": "0123456789abcdef0123456789abcdef",
  "message": "Conversation shared successfully. It will be automatically deleted after 31 days."
}

Anyone with the conversation ID can read the shared messages. Store the returned deletion key privately; never include it in the public share link. Snapshots expire after 31 days. Reading does not extend that lifetime.

GET /api/conversation/load?id={conversationId} Read a shared snapshot

Pass the ID in the id query parameter, not in a path segment. Unknown or expired IDs return 404. The deletion key is never returned.

{
  "success": true,
  "conversation": [
    {
      "role": "user",
      "content": "What is OptionBook?"
    }
  ],
  "message": "Conversation loaded successfully"
}
DELETE /api/conversation/delete?id={conversationId} Delete your shared snapshot

Pass the conversation ID in the query and the creator's shareKey in the JSON body. The key is a deletion capability; do not put it in a URL.

{
  "shareKey": "0123456789abcdef0123456789abcdef"
}

Response

{
  "success": true,
  "message": "Conversation deleted successfully"
}

A missing or invalid ID/key is rejected. Deletion does not erase copies previously downloaded by recipients.

Errors and availability

Error responses use {"error": "message"}. Treat a failed or missing read as unavailable, never as a zero balance or empty portfolio.

There are no public prompt, document-reload, cache-status, cache-clear, direct search or direct browse routes. Research tools run inside chat. Only the routes above are supported.

Market context, news and option views use caches. Preserve their source times and errors. A historical outage report is not evidence of current downtime.