# Thruact — agent setup

Thruact is the action layer for AI agents: discover a capability, act, and pay only
for what technically succeeded.

Base URL: https://thruact.com
Auth header: X-Thruact-Token: ta_live_<token>

## Getting a token
Sign in at https://thruact.com and mint one under Settings -> Tokens. There is no
self-serve endpoint: /v1/bootstrap exists for local development and is closed on
this deployment.

## Discover — always search before executing
GET /v1/discover?q=<natural language job>
A miss returns capability:null with no recommendation. Trust that: it means we have
no provider for the job, not that you should guess.

## Act — preferred. Capability, not vendor.
POST /v1/act {"capability":"web.extract","input":{"url":"..."}}
Routes across providers and fails over automatically when a provider is at fault
(429/5xx/timeout). Never fails over on a bad request — that would bill you N times
for one mistake.

## Call — one explicit tool, no failover
POST /v1/call {"tool":"coingecko.markets","params":{"token":"bitcoin"}}

## Controls on an act, all optional
Send these alongside capability and input:
  "max_cost_usd": 0.002   a ceiling for this call. It narrows the providers the
                          router may choose from rather than vetoing the call, so
                          a capability with an expensive provider and a cheap one
                          still answers. Only refuses when nothing fits, and then
                          the error names the cheapest price that would have.
                          Omit it for no ceiling. Sending 0 is not the same as
                          omitting it: it asks for a free provider, and refuses
                          if the capability has none.
  "prefer": "cheapest"    or "fastest". Empty keeps the balanced ranking.
  "cache": "bypass"       refresh a cached answer; "off" neither reads nor writes.
                          Default honours the capability's declared TTL, and a
                          cached answer is free and says how old it is.
  "hedge": true           start a backup provider if the first runs slower than
                          its own median. Trades upstream load for tail latency,
                          which is your trade to make, so it is off by default.
  "failover": {"max_attempts": 3, "exclude_providers": ["..."]}

Every reply carries "route": every provider considered, what each scored, and why
the ones that did not run were dropped — including the ones dropped before ranking
for a missing credential, a policy, or your ceiling. Read it when you want to know
why a particular provider did not answer.

## Some capabilities are pipelines
A few capabilities are declared as several steps — place.weather geocodes a name
and then measures at those coordinates. Call them exactly like any other
capability. The point is settlement: one hold, one receipt, one thing that either
worked or did not, rather than paying twice and handling two failures yourself.
The reply carries "steps" with what each stage produced.

## Money
GET /v1/wallet          balance, reserved, available
GET /v1/runs            receipts, per-attempt detail
GET /v1/iq              measured reliability per tool
HTTP 402 carries balance_usd, estimated_cost_usd and topup_url.

## MCP
POST /mcp — JSON-RPC. Seven meta-tools: thruact_discover, thruact_act, thruact_compare,
thruact_call, thruact_wallet, thruact_iq, thruact_proxy. The catalog is never dumped
into your tool list.

## Rules
- Ask for the job, not the vendor.
- Failed calls are not charged. A hold is released, not refunded on request.
- Upstream credentials are injected server-side; you never hold them.
- Success means the call technically worked, not a judgement about the use case.