Noumen API

Quickstart

1. Open the app and sign in with an Ethereum wallet on Robinhood Chain. Signing in sends no transaction.
2. In API access, create a key. Choose the models it may use and its spending limit. The key is shown once.
3. Call the API at https://www.noumen.xyz/api/v1 with Authorization: Bearer nm_sk_….

curl https://www.noumen.xyz/api/v1/chat/completions \
  -H "Authorization: Bearer $NOUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/llama-3.1-8b-instruct",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [{ "role": "user", "content": "Write a haiku about latency." }]
  }'

import os
from openai import OpenAI

client = OpenAI(base_url="https://www.noumen.xyz/api/v1", api_key=os.environ["NOUMEN_API_KEY"])
reply = client.chat.completions.create(
    model="meta-llama/llama-3.1-8b-instruct",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(reply.choices[0].message.content)

Use www.noumen.xyz. Requests to noumen.xyz are redirected, and most HTTP clients drop the Authorization header when they follow a redirect.

Try it

Create a demo API key without an account, then call the API with it here, with curl or from any OpenAI-compatible client. Demo keys are ordinary Noumen keys on a shared demo account: every request is held and settled in the billing ledger, and the key's spending limit and model list apply. Each key covers a few efficient models, at most 1,024 output tokens per request and no web tools, and expires after 24 hours. Each visitor can create 3 keys every 24 hours.

Loading the demo…

curl https://www.noumen.xyz/api/demo                 # models and limits of demo keys
curl -X POST https://www.noumen.xyz/api/demo/keys    # returns { "key": "nm_sk_…", "models": [...], "expires_at": … }

curl https://www.noumen.xyz/api/v1/chat/completions \
  -H "Authorization: Bearer nm_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<one of the key's models>", "messages": [{ "role": "user", "content": "Name three uses of embeddings." }] }'

Models

The catalog lists each model's provider, context window, maximum output, capabilities and price per million input and output tokens. Browse it on Models, or list it in OpenAI format. Without a key the list is public; with a key it is limited to the models that key may use.

curl https://www.noumen.xyz/api/v1/models

{
  "id": "meta-llama/llama-3.1-8b-instruct",
  "object": "model",
  "owned_by": "…",
  "context_length": 128000,
  "max_output_tokens": 16384,
  "capabilities": { "tools": true, "reasoning": false, "vision": true, "structured_output": true },
  "reasoning_efforts": [],
  "pricing": { "prompt": 0.15, "completion": 0.6, "cache_read": null, "cache_write": null, "unit": "usd_per_million_tokens" }
}

Chat completions

POST https://www.noumen.xyz/api/v1/chat/completions implements OpenAI Chat Completions, streaming (server-sent events) or not.

• Messages: system, developer, user, assistant and tool roles; assistant tool_calls; inline PNG, JPEG, WebP and GIF images as data URLs for vision models; cache_control hints. Message content is forwarded byte for byte, so prompt caches keep their prefixes.
• Tools: tools, tool_choice and parallel_tool_calls on models with tool calling.
• Controls: temperature, top_p, top_k, min_p, repetition_penalty, frequency_penalty, presence_penalty, stop, seed, response_format, logit_bias, logprobs, top_logprobs, and reasoning_effort, mapped to the nearest effort the model offers.
• Output budget: max_tokens or max_completion_tokens, lowered to the model's output limit; 16,384 when omitted.
• Usage: set stream_options.include_usage to receive token counts in the final chunk. X-Request-ID is the Noumen usage ID shown in your billing history.
• Not supported: n other than 1, audio output, file inputs and remote image URLs are rejected. Any other field is dropped, so add-ons with separate charges never run unasked.
• Web tools: the optional web_tools field, { "search": true, "readLinks": true, "youtube": false }, retrieves sources before generation. Each tool run is billed separately from the generation and reported as a noumen.tool event.
• On-chain analysis: token_tools: true gives a tool-calling model 22 live analysis tools. 14 cover tokens on Solana, Ethereum, Base, BNB Chain and Robinhood Chain: search, overview, holders and security, holder groups, social activity, market-cap charts, on-chain contract reads, trending and hot boards, active tokens, signals, wallet profiles, market prices and chain activity. 8 cover tokenized stocks and real-world assets (index funds, treasuries, commodities, credit) on Robinhood Chain: search and session scans by asset class, quotes with the token's premium to its share and how unusual the move is, price charts, technical indicators, earnings with past reactions, news, and on-chain supply, holders, pools and the ERC-8056 share multiplier. Noumen runs the model in rounds, executes its tools between them and returns one completion; your own tools keep working alongside. Token data is free; each model round is a separately billed request under the same X-Request-ID. Lookups are reported as noumen.tool events on streams and as tool_runs on JSON responses.

curl https://www.noumen.xyz/api/v1/chat/completions \
  -H "Authorization: Bearer $NOUMEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "meta-llama/llama-3.1-8b-instruct", "token_tools": true,
       "messages": [{"role": "user", "content": "What is trending on Solana right now, and is the top token safe to research?"}]}'

Coding agents

Coding agents that accept an OpenAI-compatible provider work with Noumen, including OpenCode, Cline, Roo Code, Kilo Code, Continue and Aider. Choose a model with tool calling. In the app, API access generates a ready opencode.json; the minimal form is:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "noumen": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Noumen",
      "options": { "baseURL": "https://www.noumen.xyz/api/v1", "apiKey": "{env:NOUMEN_API_KEY}" },
      "models": { "meta-llama/llama-3.1-8b-instruct": { "name": "meta-llama/llama-3.1-8b-instruct", "tool_call": true } }
    }
  }
}

For Cline, Roo Code and Kilo Code, choose the OpenAI Compatible provider and enter the base URL, your key and a model ID.

Spending limits

• Per key: every key has a lifetime spending limit set when it is created. Requests that would pass it are refused with key_limit_reached. A key can also be restricted to chosen models.
• Per account: a monthly limit covers the workspace and every key together and is refused with monthly_limit_reached. Change it in the app.
• Holds: before a request starts, its largest possible cost (the prompt plus the full output budget at the model's rates) is held against the limits and the balance. The hold shrinks to the reported usage when the response ends and settles to the actual charge.
• Concurrency: each account has a limit on open API requests; further requests get concurrency_limit until one finishes.

Billing

Inference is charged per token at the rates shown for each model, in US dollars per million input and output tokens. Prompt-cache reads and writes use the model's cache rates where it publishes them. The app's Usage & billing lists every request with its model, tokens, charge and status.

On-chain balance deposits are not open yet.

Billing records stay private to your account. Itemized usage is never published as on-chain transactions.

Holder credits

Launch giveaway: the first 100 accounts whose wallet bought the Noumen token in its trading pool, and still holds at least $1 of the tokens it bought, can claim $10.00 in inference credits under Holder credits in the app. Each account, wallet and purchase can claim once. Tokens received by transfer do not count.

Fee-funded holder credits, paid from a share of protocol fees, are not active yet. When they start, this section will state the fee share, the funding address and its transactions, so every credit can be traced on chain.

Privacy

• Your workspace stays on your device. Conversations, projects, files and preferences are stored only in your browser, encrypted with AES-256-GCM. Each wallet account has its own encrypted profile, which opens only after you sign in with that wallet, and its encryption key can never be exported from the browser.
• No copies on our servers. Prompts and responses pass through Noumen only to generate the answer; they are never stored.
• Billing keeps only what billing needs: the model, token counts, charge and status of each request, private to your account and never published on chain.

Network

Noumen uses Robinhood Chain mainnet (chain ID 4663), an Ethereum layer 2 that pays network fees in ETH, for wallet sign-in, deposits and the Noumen token.

Noumen token contract: 0xe9B7B7D55Ed2Ca56B017c569F3c5dd30dD31fEfc. This is the only official address; it is also linked from @NoumenLabs.

Errors

Errors use the OpenAI envelope, { "error": { "message", "type", "param", "code" } }. Errors during a stream arrive as a final data: frame with the same shape.