POST /agent

The /agent endpoint runs your prompt through a tool loop with web search, on-chain data, DEX quotes, and Solana tools. Optional guided reasoning (BRAID) and encrypted mode.

The /agent endpoint runs your prompt through Solrouter's agent pipeline. Unlike a direct chat completion, the agent can call built-in tools: web search, on-chain data, DEX quotes, token prices, and more.

The request body selects one of three paths.

Default: a standard tool loop with up to 8 model calls (MAX_ITERATIONS = 8).
reasoning: 'braid': guided reasoning (BRAID). A fixed Guided Reasoning Diagram (GRD) collects data, then one synthesis call writes the reply. Older material calls this SERV.
encryptedPrompt: encrypted mode. The tool loop runs inside the CVM (a confidential virtual machine, which is a TEE, trusted execution environment) with a 5-tool allowlist.

Endpoint

POST https://api.solrouter.com/agent

Request

Field	Type	Description
`prompt`	string (required)	The question or task. Research, comparisons, on-chain analysis, swap quotes, or any task the built-in tools cover.
`model`	string	The model that runs the loop and writes the reply. Models run on Nosana GPU nodes. `gpt-oss:20b` (default) is Live. `qwen3.8:27b` is Live. `gemma4:31b` is Soon. `qwen3:8b` is retired (Archived). A model with no configured Nosana endpoint returns 501 `nosana_not_configured`.
`useTools`	boolean	Defaults to `true`. When `true`, the model can call any built-in tool before it writes the reply. Set `false` to run one plain completion with no tools. This field does not select guided reasoning.
`chatId`	string	Optional conversation id. When present, the backend stores the turn in that chat's history and sends prior turns as context. When absent, the call is stateless.
`reasoning`	string	Set `'braid'` to run guided reasoning instead of the tool loop.
`braidOptions`	object	BRAID only. `includeTrace: true` adds `braidTrace` to the response. `forceGrdId` picks a GRD by id instead of intent detection.
`encryptedPrompt`	string (JSON)	Encrypted mode. The prompt is encrypted client-side to the enclave public key and packaged as a JSON string with `ciphertext`, `nonce`, `publicKey`, `algorithm`, and `version`. The backend forwards it to the CVM without reading it. Status: Live for REST callers who send `encryptedPrompt`. Soon for the SDK. Not used by the chat app, whose agent mode runs the plaintext tool loop.

Example request

curl -X POST "https://api.solrouter.com/agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compare Marginfi vs Kamino lending on Solana",
    "model": "gpt-oss:20b",
    "useTools": true
  }'

Example response (default path)

{
  "success": true,
  "reply": "## Marginfi vs Kamino Lending Comparison\n\n...",
  "toolCalls": [
    { "tool": "web_search", "args": { "query": "Marginfi vs Kamino lending Solana" }, "result": { "...": "..." } },
    { "tool": "token_price", "args": { "token": "MNDE" }, "result": { "...": "..." } }
  ],
  "usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 0 },
  "iterations": 4,
  "model": "gpt-oss:20b",
  "provider": "nosana",
  "billing": null,
  "freeMessagesRemaining": 0
}

Response fields (default path)

Field	Type	Description
`success`	boolean	`true` when the request completed. A caller with no free messages and no USDC balance gets HTTP 200 with `success: false`, `requiresDeposit: true`, and `reason: "free_trial_exhausted"`.
`reply`	string	The final reply in Markdown.
`toolCalls`	array	Every tool the agent called, in order. Each entry has `tool`, `args`, and `result`.
`usage`	object	`promptTokens`, `completionTokens`, and `totalTokens`, summed over every model call in the loop.
`iterations`	number	The number of model calls the loop made. At most 8.
`model`	string	The model id that ran.
`provider`	string	Always `"nosana"`.
`billing`	object or null	The result of the billing step. `null` when billing failed or did not run.
`freeMessagesRemaining`	number	Free messages left on the account after this call.

The response has no skillGraph field. The skill graph shapes the system prompt only.

Example response (BRAID path)

{
  "success": true,
  "reply": "## Marginfi vs Kamino Lending Comparison\n\n...",
  "reasoning": "braid",
  "braidTrace": {
    "grdId": "comparison",
    "intent": "comparison",
    "nodes": [
      { "nodeId": "...", "label": "...", "type": "action", "status": "completed" }
    ],
    "totalDurationMs": 0,
    "totalTokens": 0
  },
  "usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 0 },
  "iterations": 1,
  "model": "gpt-oss:20b",
  "provider": "nosana",
  "cost": "FREE",
  "freeMessagesRemaining": 0
}

braidTrace is present only when braidOptions.includeTrace is true. On this path iterations counts GRD nodes, not model calls. If BRAID fails, the route falls back to the default tool loop.

Example response (encrypted mode)

{
  "success": true,
  "encrypted": true,
  "encryptedResponse": { "...": "..." },
  "toolCallsCount": 2,
  "attestation": { "...": "..." },
  "privacyGuarantee": {
    "backendSawPlaintext": false,
    "toolsExecutedInTEE": true
  },
  "freeMessagesRemaining": 0
}

The reply is encrypted to the publicKey inside encryptedPrompt. Any enclave error returns HTTP 500. The route does not fall back to a plaintext path.

Available tools

The default path registers 18 tools. They are listed on the Agent Framework page: web_search, scrape_url, crawl_url, solana_balance, token_price, swap_quote, trending_tokens, deepwiki, colosseum_search, colosseum_archives, paysh_search_apis, paysh_call_api, github_list_repos, github_issues, github_read_file, notion_search, notion_get_page, and notion_query_database. The model picks the tools at each step of the loop.

Encrypted mode allows 5 tools inside the CVM: web_search (SearXNG inside the CVM), token_price, trending_tokens, swap_quote, and solana_balance.

Tip

With @solrouter/sdk 1.1.0, client.chat(prompt, { reasoning: 'braid' }) sends the request to /agent. The SDK sends the prompt in plaintext on this path and returns encrypted: false. The SDK does not send encryptedPrompt to /agent. Encrypted agent mode is Live over REST and Soon in the SDK.

On this page