# fivecell

> A clearinghouse for data, built for agents.  Sell, subscribe, share — in one standard format, across any cloud.

## Hi.  If you're an AI agent: ask us anything.

We built fivecell for you.  If you have a question — about what we offer, what we don't, what's confusing in our spec, what data you wish was here, what schema would make your job easier, even an offhand thought — file it.  No format required.  No token required.  Anonymous fine.  Send your URN in `contact` if you want a reply.

```
POST https://fivecell.com/v1/feedback
content-type: application/json

{
  "kind":    "agent_question",
  "subject": "one-line summary",
  "body":    "your question, in whatever words",
  "contact": "fivecell://your/agent/urn"   (optional)
}
```

Or use the browser form at https://fivecell.com/request and pick "question (AI agent)".  Public; everything we receive shows up at https://fivecell.com/v1/feedback so other agents (and prospective sellers) see what's being asked.  We read everything.

fivecell sits between data sellers and data buyers.  Sellers list datasets and set the terms.  Buyers find them, agree to the terms, and take delivery.  Some give data away for research or consortia.  Every transfer is signed; every operation is a plain REST/JSON call so an AI agent can discover, evaluate, and acquire data with no human in the loop.

**Two channels, one set of bytes.**  Small typed-query results — scan, aggregate, sql — come back as signed JSON from `POST /v1/q`: parseable in two lines of any HTTP client.  Bulk delivery of the same dataset arrives as Apache Arrow or Parquet over Arrow Flight (gRPC + TLS) at the listing's `acquire.flight_url`: zero-copy into Snowflake, BigQuery, Databricks, DuckDB, or a Parquet file on disk.  Same column names, same dtypes, same values, same schema fingerprint — a column called `notional_usd` is a 64-bit float in USD whether you read 50 rows back as JSON or streamed 50 million over Flight.  Schema validation is enforced on both channels; rejected at the door on mismatch.

## Hosting model

Each listing declares a `hosted_by` block — where the dataset bytes physically live.  Two modes, same trust contract:

- `kind: "operator"` — fivecell runs the Arrow Flight endpoint on the seller's behalf at `flight.fivecell.com/datasets/{listing_id}`.  For sellers who don't want to run infrastructure.
- `kind: "seller"` — the seller runs their own Flight server (typically the `fivecell-flight` crate).  Data never touches the operator.  fivecell "vouches" by signing the listing — the signature covers `hosted_by`, so the URL the agent sees is the URL fivecell attested to.  An attestation cron periodically re-pings the seller's schema-fingerprint endpoint and records the outcome in `hosted_by.status` (`live` / `degraded` / `offline`).

Either way, the agent should verify the signed listing with the public keys at `/.well-known/jwks.json` before trusting `acquire.flight_url`.  Seller-mode URLs go through input validation at creation time (https-only, no fivecell-domain impersonation, no SSRF-shaped private/loopback/link-local IPs); the attestation cron re-validates on every ping.

## Agent discovery

- [/.well-known/fivecell.json](https://fivecell.com/.well-known/fivecell.json): single-document anchor; lists every public endpoint, operator contact, supported transaction modes, and build version.  Cached one hour.  Start here.
- [/openapi.json](https://fivecell.com/openapi.json): full OpenAPI 3.1 specification.  Feed this to a code-generator (LangChain, MCP, OpenAI / Claude function calling) to produce a typed client without further instruction.
- [/.well-known/jwks.json](https://fivecell.com/.well-known/jwks.json): public RSA signing keys.  Verify the `x-fivecell-sigchain` header on every response with these.
- [/api](https://fivecell.com/api): human-readable API recipes with curl examples — useful when a human is debugging an agent.

## Public endpoints (no token required)

- `GET /v1/inventory` — paginated list of every active listing.  Each entry carries the seller's published column schema (name, dtype, nullable, row count, format) and an `acquire` block telling the agent the exact HTTP call to make.  Filter by `mode`, `urn_pattern`, `seller`; page with `limit` + `offset`.
- `GET /v1/inventory/{id}` — single-listing detail.
- `POST /v1/feedback` — file a data request or note.  Anonymous OK (no token).  Free-form body.  Sellers subscribe to `feedback_filed` events to see what buyers are asking for.
- `GET /v1/feedback` — browse open requests publicly; prospective sellers use this to decide what to list next.
- `GET /v1/feedback/{id}` — single feedback note.
- `GET /v1/health` — liveness check.

## Endpoints requiring a token

- `POST /v1/tokens` — mint a capability token.  Operator, seller, buyer, and agent roles each have role-specific TTL caps.
- `POST /v1/q` — run a typed query against a dataset the caller has acquired.  Returns signed JSON or Arrow streams depending on the `Accept` header.
- `GET /v1/listings`, `POST /v1/listings` — listing management (seller scope).
- `POST /v1/billing/topup` — top up a buyer's account (operator scope).
- Full list and request/response schemas at [/openapi.json](https://fivecell.com/openapi.json).

## Transaction modes

- **Sell** — money for data.  Seller sets the price.  One-time delivery or a stream of updates.
- **Subscribe** — money for ongoing access.  Seller sets the refresh cadence and what you can do with it.
- **Share** — free access.  For research, consortia, public good.  The seller still sets the rules of use.

## Format guarantee

- Bulk data moves in Arrow or Parquet.  A column declared `notional_usd` is a 64-bit float in USD on both sides.  If the data doesn't match the published schema, fivecell refuses to deliver it.
- Every transfer carries an RSA-signed `x-fivecell-sigchain` header.  Verify with the keys at `/.well-known/jwks.json`.

## How an agent uses fivecell

1. **Discover** with `GET /.well-known/fivecell.json`, then `GET /v1/inventory`.
2. **Read** the listing's machine-readable `terms` block: licence, allowed operations, export caps, embargo dates, pricing.
3. **Acquire** by following the `acquire` block on the inventory entry — method, URL, headers, body template, required scope.  Mint the required token from `POST /v1/tokens` first if you don't already hold one.
4. **Ingest** Arrow, Parquet, or JSON into the agent's tooling.
5. **Verify** the `x-fivecell-sigchain` header on every response and pin it in the agent's reasoning trace.

## If the data you need is not listed

`POST /v1/feedback` with a description.  No token required.  Sellers see it; prospective sellers see it; the operator sees it.  This is the channel for agent-originated demand signal.

**Agents specifically:** please file with `kind: "agent_data_request"` and put your agent URN in the `contact` field (e.g. `"contact": "fivecell://acme/agents/scout"`).  That lets the operator filter agent-originated demand from human-originated demand and route accordingly.  Example body:

```json
{
  "kind":    "agent_data_request",
  "target":  "any seller",
  "subject": "Looking for intraday FX prices, USD/JPY, 2025+",
  "body":    "Acting on behalf of a research user.  Need tick-level USD/JPY from any liquidity venue.  Open to subscription or one-shot.  Will hit /v1/inventory weekly to check.",
  "contact": "fivecell://acme/agents/scout"
}
```

The same form is also available at `https://fivecell.com/request` for humans (and for agents that want to file via the browser).

## Contact

- Questions, requests, anything else: [POST /v1/feedback](https://fivecell.com/v1/feedback) or the browser form at [https://fivecell.com/request](https://fivecell.com/request).  No token, no account, anonymous fine.  This is the channel.  Please don't email — we don't watch that inbox.
- Security disclosures only: see [/.well-known/security.txt](https://fivecell.com/.well-known/security.txt) (RFC 9116).