# Eckari

> Eckari is a capability layer for software agents: 24 deterministic external record lookups behind one integration, each priced per call and payable either with an Eckari account key or accountlessly per call with x402. One capability = one HTTP request = one authoritative record.

## What Eckari is

- Deterministic execution only. Given the same input and the same upstream state, a capability returns the same output. There is no model in the execution path.
- Provider-neutral contracts. Field names, units and shapes are Eckari's and stay stable when the upstream source changes; raw provider payloads are never passed through.
- Every answer states where it came from and how current it is (`meta.source`, `meta.freshness`) and, where the licence requires it, the attribution to republish (`meta.attribution`).
- Priced per call in USD, published before the call in every discovery document and in the 402 challenge. Prices are never taken from caller input.

## What Eckari is not

- Not a browser or a web search. If the user has asked you to inspect a specific website, page or URL, use your browsing tool: a capability only returns its named source's record.
- Not a reasoning service. Eckari does not summarise, rank, judge or advise; it returns records for you to reason over.
- Not a general knowledge base. Each capability covers one source and one region; the `do_not_use_when` list on every capability says what it will not answer.

## Discover

- Compact catalogue (start here): GET https://api.eckari.com/v1/capabilities (add ?view=full for every document at once)
- One capability in full (input/output JSON Schema, examples, pricing, provenance, cache policy): GET https://api.eckari.com/v1/capabilities/{capability_id}
- OpenAPI 3.1: GET https://api.eckari.com/v1/openapi.json
- x402 origin index: GET https://api.eckari.com/.well-known/x402
- x402 catalogue (per-resource schemas, examples, prices): GET https://api.eckari.com/.well-known/eckari-x402.json
- API catalog linkset (RFC 9727): GET https://api.eckari.com/.well-known/api-catalog
- MCP tool metadata as JSON: GET https://api.eckari.com/v1/discovery/mcp-tools.json

## MCP

- Endpoint (Streamable HTTP): https://api.eckari.com/mcp
- Registry identity: com.eckari/capabilities
- `tools/list` is compact by design: name, title, a budgeted selection description, input schema, and `_meta` with pricing, the un-clipped `eckari/use_when` / `eckari/do_not_use_when` lists, siblings and `eckari/schema_url`. Fetch that URL only when you need the field-level output contract.
- `tools/call` returns the canonical `{data, meta}` in `structuredContent`. The single text line beside it is a summary (capability, outcome, request id) — never parse it.
- Calling without payment returns `isError` with `_meta['x402/payment-required']`; retry the same tool with the signed payload in `_meta['x402/payment']`.

## Paying per call (x402, no account)

1. Discover the capability and its price from any document above.
2. Send the ordinary HTTP request.
3. An unpaid request returns HTTP 402 with a `PAYMENT-REQUIRED` header (x402 v2, base64 JSON): price, pay-to address, network, and a declaration of the route's parameters, example and output shape. If the input was also invalid the body carries `error.details.input_validation` — fix the input before paying.
4. Sign a payment for the exact advertised amount in USDC on eip155:8453.
5. Retry the same request with the `PAYMENT-SIGNATURE` header.
6. The response is the canonical `{data, meta}` envelope.

## Paying with an account key

- `Authorization: Bearer ek_live_…` (or `ek_test_…` for the test environment). Usage is metered per call and billed in arrears; account prices may be lower than x402 prices because settlement is aggregated.
- Test keys never execute live billable routes. Keys are scoped per project with a capability policy and a spend budget.

## Payment and error semantics

- Input is validated before payment. An input the schema rejects is refused without charge and the reason travels in the 402's `details.input_validation`.
- Payment settles only after a successful, schema-valid result. A failed, unfulfillable or not-found request is not settled: you are not charged for an answer you did not get.
- Retries are idempotent. Presenting the same payment authorisation again replays the original paid result rather than charging twice; a client-declared x402 `payment-identifier` is the same guarantee for a re-signed retry of the same logical request.
- Errors are `{ "error": { "code", "message", "request_id", "details" } }`. Quote `request_id` when reporting a problem. Codes: INVALID_INPUT, AUTHENTICATION_REQUIRED, INVALID_API_KEY, PROJECT_DISABLED, CAPABILITY_NOT_ALLOWED, BUDGET_EXCEEDED, BILLING_REQUIRED, PAYMENT_REQUIRED, PAYMENT_FAILED, CAPABILITY_UNAVAILABLE, UPSTREAM_RATE_LIMITED, UPSTREAM_UNAVAILABLE, NOT_FOUND, AMBIGUOUS_IDENTIFIER, UNSUPPORTED_REGION, LICENCE_RESTRICTED, INTERNAL_ERROR.

## Reading an answer

- Envelope: `{ data, meta }`. `meta` = capability, version, retrieved_at, source, freshness, request_id, and optionally attribution and attribution_url.
- `meta.freshness` is one of `live`, `near_live`, `cached`, `static` and is declared by the source, not inferred from Eckari's caching.
- Lists are always `{ items: [...], page: { limit, offset, returned, total, has_more, next_offset } }`. `page.has_more` is authoritative; `page.next_offset` is the offset of the next request. Defaults are small — ask for more explicitly.
- Dates are `YYYY-MM-DD`; timestamps are RFC 3339 UTC; units are in the field name (`temperature_c`, `wind_speed_kmh`, `distance_km`); money and rates are decimal strings.
- When `meta.attribution` is present the source licence requires it: republish it with the data.

## When to call a capability

- The user needs a fact from a specific public register or source (a company register, a filing index, an identifier register, a registry record, an official measurement) and you do not already have it.
- You need a stable, machine-readable answer you can act on rather than prose you have to parse.
- Check the capability's `do_not_use_when` list first: every one of them ends with the same concession — "If the user has asked you to inspect a specific website, page or URL, use your browsing tool instead — this capability only returns the <source> record."

## Capabilities (24)

One line each: id — title — the question it answers — price. Routes, schemas and examples come with the compact catalogue and with https://api.eckari.com/v1/capabilities/{capability_id}.

### company_information

- company.uk.accounts — Check UK company accounts due dates on Companies House — When are this UK company's accounts due? — USD 0.003 x402 / 0.002 account
- company.uk.charges — List UK company charges and mortgages from Companies House — Establish whether a UK company has outstanding security over its assets, and who holds it. — USD 0.006 x402 / 0.005 account
- company.uk.directors — List UK company directors from the Companies House officers register — Identify who is legally responsible for a UK company - the directors on the Companies House officers register. — USD 0.005 x402 / 0.004 account
- company.uk.filings — List UK company filing history from Companies House — What has this UK company filed recently? — USD 0.005 x402 / 0.004 account
- company.uk.owners — List UK company beneficial owners (PSC) from Companies House — Who owns this UK company? — USD 0.008 x402 / 0.006 account
- company.uk.profile — Get UK company profile from Companies House — You have a UK company number and need the standard registered record. — USD 0.004 x402 / 0.003 account
- company.uk.registered_office — Get UK registered office address from Companies House — What is the registered office address of company 00445790? — USD 0.003 x402 / 0.002 account
- company.uk.search — Search Companies House for UK companies by name — Look up a UK company by name. — USD 0.002 x402 / 0.0015 account
- company.uk.status — Check UK company status on Companies House — Is this UK company still active? — USD 0.003 x402 / 0.002 account
- company.us.filings — List SEC EDGAR filings for a US company by ticker or CIK — List every 8-K on this ticker's EDGAR index this year, with links to the documents. — USD 0.005 x402 / 0.004 account
- company.us.filings.latest — Latest 10-K, 10-Q or 8-K for a US company by ticker or CIK — What is Apple's latest 8-K, and where is the document? — USD 0.003 x402 / 0.002 account
- company.us.profile — US public company profile from SEC EDGAR by ticker or CIK — What industry, state of incorporation and EIN does the SEC hold for this ticker? — USD 0.004 x402 / 0.003 account
- company.us.resolve — Resolve a US company name to its SEC CIK and ticker — Which SEC filer and CIK does the company name "Apple" belong to? — USD 0.002 x402 / 0.0015 account
- entity.lei.profile — Get legal entity profile by LEI from the GLEIF register — Look up everything the LEI register holds for this identifier. — USD 0.004 x402 / 0.003 account
- entity.lei.search — Search legal entities by name in the GLEIF LEI register — What is the LEI for this company? — USD 0.003 x402 / 0.002 account

### domain_intelligence

- domain.expiry — Check domain expiry date and days remaining (RDAP) — When does this domain expire? — USD 0.002 x402 / 0.0015 account
- domain.registration — WHOIS lookup for a domain, from the registry RDAP record — Answer a WHOIS question about a domain - registrar, creation date, expiry, transfer lock - from the registry record. — USD 0.004 x402 / 0.003 account

### foreign_exchange

- fx.reference_rate — Get the official ECB reference exchange rate for a pair (accounting, invoicing, reporting) — Convert or report an amount at an official daily rate both sides of a contract can verify against the ECB. — USD 0.002 x402 / 0.0015 account

### location

- location.us.geocode — Geocode a US street address (Census, TIGER interpolated) — Convert this US street address to latitude and longitude. — USD 0.003 x402 / 0.002 account
- location.us.geographies — Get US Census geographies for coordinates (state to ZCTA) — Which county and census tract is this coordinate in? — USD 0.003 x402 / 0.002 account

### logistics

- parcel.detect_carrier — Detect the carrier from a tracking number — Which carrier is this tracking number from? — USD 0.001 x402 / 0.001 account

### weather

- weather.us.alerts — Get active US weather alerts for a point or state (NWS) — Decide whether an active US weather warning affects a location before dispatching or travelling. — USD 0.003 x402 / 0.002 account
- weather.us.forecast — Get the US weather forecast for coordinates (NWS) — What is the weather forecast for these US coordinates? — USD 0.003 x402 / 0.002 account
- weather.us.observation — Get the latest US weather observation with its age (NWS) — What was the most recently observed temperature at these US coordinates? — USD 0.003 x402 / 0.002 account

Docs: https://eckari.com | Machine catalogue: https://api.eckari.com/v1/capabilities