Developer documentation

Machine-readable references

• GET https://api-staging.eckari.com/v1/openapi.json — OpenAPI 3.1
• GET https://api-staging.eckari.com/v1/capabilities — catalogue with schemas, prices, examples
• GET https://api-staging.eckari.com/.well-known/eckari-x402.json — x402 resource catalogue
• GET https://api-staging.eckari.com/v1/discovery/mcp-tools.json — MCP tool metadata
• GET https://api-staging.eckari.com/llms.txt

Access modes

Capabilities declare two channel prices. Account access (Authorization: Bearer ek_live_…) is metered and billed in arrears; the developer portal and API keys are not yet enabled in this environment, so keys are rejected with INVALID_API_KEY. Accountless x402 pays per call: send the request without credentials, receive 402, sign the payment, retry.

x402 flow

1. Call the capability. Input is validated first — malformed requests get 400 and are never charged.
2. Unpaid requests receive 402 with a base64 PAYMENT-REQUIRED header (x402 v2 PaymentRequired: scheme exact, network, USDC amount, payTo).
3. Create a payment payload with an x402 client (for example @x402/fetch) and retry with PAYMENT-SIGNATURE.
4. The gateway verifies the payment, executes the upstream work, settles, and returns 200 with a PAYMENT-RESPONSE header carrying the settlement transaction. If fulfilment fails, nothing is settled.

# 1. Unpaid request → 402 challenge
curl -i "https://api-staging.eckari.com/v1/companies/uk/01234567/status"

# 2. Paid request (client libraries do this for you)
curl -i "https://api-staging.eckari.com/v1/companies/uk/01234567/status" \
  -H "PAYMENT-SIGNATURE: <base64 x402 v2 PaymentPayload>"

// TypeScript client using @x402/fetch + viem (Base Sepolia testnet)
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`);
const client = new x402Client().register("eip155:84532", new ExactEvmScheme(signer));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPayment("https://api-staging.eckari.com/v1/companies/uk/01234567/status");
console.log(await res.json());

Response envelope

{
  "data": {
    "company_number": "01234567",
    "company_name": "EXAMPLE TRADING LIMITED",
    "status": "active",
    "status_detail": null,
    "is_active": true,
    "date_of_cessation": null,
    "source_status": "active"
  },
  "meta": {
    "capability": "company.uk.status",
    "version": "1.0.0",
    "retrieved_at": "2026-08-17T12:00:00Z",
    "source": "companies_house",
    "freshness": "live",
    "request_id": "req_…"
  }
}

meta.source names the upstream register; meta.freshness is one of live, near_live, cached, static. Every response carries an x-request-id header.

Errors

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No register entry found for this identifier",
    "request_id": "req_…",
    "details": null
  }
}

MCP

Tool metadata for every capability is generated from the registry. A hosted Eckari MCP server is planned for the next phase; the tool definitions below are what it will expose (9 tools, server eckari).

• company_uk_accounts
  Get UK company accounts summary and due dates
  x402 USD 0.003
• company_uk_charges
  List UK company registered charges (mortgages and security)
  x402 USD 0.005
• company_uk_directors
  List UK company directors and officers
  x402 USD 0.005
• company_uk_filings
  List UK company filing history
  x402 USD 0.005
• company_uk_owners
  List UK company beneficial owners (persons with significant control)
  x402 USD 0.005
• company_uk_profile
  Get UK company profile
  x402 USD 0.004
• company_uk_registered_office
  Get UK company registered office address
  x402 USD 0.003
• company_uk_search
  Search UK companies by name
  x402 USD 0.004
• company_uk_status
  Check UK company status
  x402 USD 0.003

Full definitions: https://api-staging.eckari.com/v1/discovery/mcp-tools.json