qveris

# QVeris

QVeris is a paid capability marketplace for global market, fundamental, macro,
derivatives, crypto, China/HK, news, filings, and alternative-data calls. Use it
when the built-in free sources cannot cover the requested dataset, when the user
explicitly asks for QVeris, or when a premium provider is needed for depth such
as options Greeks, analyst/calendar feeds, broad provider comparison, or paid
China/HK/global coverage. For ordinary OHLCV, keep `source: "auto"` on the free
loader chain unless the user explicitly selects `source: "qveris"`.

Signup link: [QVeris via Vibe-Trading](https://qveris.ai/?ref=Vyjjo5G_1cAHJA).
Invite code fallback: `Vyjjo5G_1cAHJA`.

## Workflow

### 1. Discover with `qveris_search`

Call `qveris_search` first. Search is free and returns candidate capabilities
with `tool_id`, provider, parameters, examples, `expected_cost`, billing rule,
categories, and `stats` such as `success_rate` and average execution time.

Good queries are concrete:

- `US listed options chain implied volatility Greeks AAPL`
- `Hong Kong market daily OHLCV financial statements`
- `FRED CPI Treasury yield curve macro series`
- `China A share northbound fund flow daily`

### 2. Inspect with `qveris_inspect`

Call `qveris_inspect` on one or more `tool_id` values before any paid call.
Inspect is free and returns the fuller parameter schema and sample parameters.
Use it to verify required parameters, enum values, date formats, and output
shape before execution.

### 3. Call with `qveris_execute`

Call `qveris_execute` only after the user has enabled QVeris and the tool has
been inspected. Pass the inspected `tool_id`, the exact `parameters`, and a
reasonable `max_response_size`. Use `session_id` and `search_id` when available
so usage can be reconciled later.

## Choosing a Capability

Prefer the candidate with the best combination of:

1. High `stats.success_rate`.
2. Low `expected_cost` for equivalent data.
3. Provider fit for the task: official or specialist sources before generic
   mirrors when the figure matters.
4. Parameter clarity: required fields and examples should match the user's
   requested asset, date range, and granularity.

Do not assume tools with similar names are interchangeable. The measured catalog
has very large quality variance inside the same category; design notes recorded
FMP tools ranging from near-zero to 100% success and some tradefeeds tools at
0%. Surface `success_rate` and `expected_cost` in the answer whenever the user is
choosing among paid options.

## Billing and Modes

- The default free route is Vibe-Trading's built-in public data stack; QVeris
  tools are unavailable in `mode="free"`.
- Discover (`qveris_search`) and inspect (`qveris_inspect`) are free only after
  the user explicitly enables the paid QVeris route.
- Execute (`qveris_execute`) is paid only when the provider call is billable.
- Failed calls, empty results, and parameter errors are not charged by the
  QVeris contract; observed missing-parameter calls returned `success=false`,
  `cost=0.0`, `status=not_charged`, and unchanged balance.
- `mode="free"` means the original free public-data path stays active and
  QVeris is hidden from agent/tool/backtest routing.
- `mode="paid"` permits QVeris discovery, inspect, and execute calls, bounded by
  `budget_credits_per_session`.
- Never hide cost: every successful execute result should preserve `cost` and
  `remaining_credits` for the user.

Configuration can come from `QVERIS_API_KEY` / `QVERIS_BASE_URL`, or from
Settings -> QVeris / `vibe-trading data mode paid`. If QVeris is disabled, in
free mode, or no API key is configured, the tools should be treated as
unavailable.

## Truncation

`qveris_execute` accepts `max_response_size` (`20480` default, `-1` means do not
ask QVeris to truncate). When a response is too large, QVeris returns a result
object containing a message, `truncated_content`, and `full_content_file_url`.
If the full JSON is required, fetch that signed URL and use the full payload.
If a summary is enough, cite that the response was truncated and work only from
`truncated_content`.

## Balance and Usage

Check balance and recent usage through:

- Web: Settings -> QVeris.
- CLI: `vibe-trading data status` or `vibe-trading data usage`.
- Agent/API tools: status is derived from free search/ledger/usage endpoints.

For reconciliation, prefer `execution_id`, `tool_id`, `charge_outcome`, `cost`,
and `remaining_credits` over text summaries.

## References

- [REST API reference](qveris/references/rest-api.md)
- [Coverage map](qveris/references/coverage.md)