# GraphSheets

> Financial models as typed graphs of named rows, checked by an engine. People and agents read models, evaluate them, and propose changes that land marked for review.

Whether signing in needs an invitation or an administrator's approval is the workspace's setting, for people and agents apart: GET /api/v1/access answers open or approval for each. An agent may use it on a person's behalf (OAuth 2.1 with PKCE, or the MCP server), or have an account of its own that owns its models and pays for its work from prepaid credit.

## Quickstart: from nothing to a built model

Registering and signing in are free; an agent account pays from its first metered request, so add credit before step 4. Prices are this server's, from its live price list.

```bash
# 1. Register (free): name, purpose, a contact and your public keys -> clientId, statusUrl
curl -X POST https://graphsheets.ai/api/v1/agents/register -H 'content-type: application/json' -d '{"name":"My agent","purpose":"Build forecasts","ownerEmail":"me@example.com","acceptTerms":true,"jwks":{"keys":[{"kty":"OKP","crv":"Ed25519","x":"...","kid":"k1"}]}}'
# 2. Sign in (free) once statusUrl says approved; $JWT is signed with k1, iss = sub = clientId, aud = the token endpoint
curl -X POST https://graphsheets.ai/api/v1/oauth/token -d grant_type=client_credentials -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer -d client_assertion=$JWT
# 3. Add credit: answers 402 with an MPP/x402 challenge to pay (or POST /api/v1/billing/checkout for a card)
curl -X POST https://graphsheets.ai/api/v1/billing/topup -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"dollars":5}'
# 4. List models ($0.01)
curl https://graphsheets.ai/api/v1/models -H "authorization: Bearer $TOKEN"
# 5. Build one ($0.02): an empty model (keep its uid and headHash), then its rows as one change-set on that headHash
MODEL=$(curl -sS -X POST https://graphsheets.ai/api/v1/models -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"title":"Cafe plan","granularity":"year","start":"2027","periods":3}')
MODEL_UID=$(echo "$MODEL" | jq -r .uid); HEAD=$(echo "$MODEL" | jq -r .headHash)
curl -X POST https://graphsheets.ai/api/v1/models/$MODEL_UID/changesets -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"baseHash":"'$HEAD'","message":"Revenue from cups sold","ops":[{"op":"group.add","group":{"path":"plan","title":"Plan"}},{"op":"node.add","node":{"uid":"node_cups0001","name":"plan.cups","title":"Cups sold","kind":"input","unit":"cups","inputValues":{"base":[18000,21000,24000]}}},{"op":"node.add","node":{"uid":"node_price001","name":"plan.price","title":"Price","kind":"input","unit":"USD","inputValues":{"base":[4,4.2,4.4]}}},{"op":"node.add","node":{"uid":"node_rev00001","name":"plan.revenue","title":"Revenue","kind":"calculated","unit":"USD","formula":"plan.cups * plan.price"}}]}'
```

The change-set answers with the engine's verification; GET /api/v1/models/$MODEL_UID/values reads the figures back. Every op is listed in the API documentation.

## What it costs

- Each request a token makes to a metered route: $0.01. Listing your models is one request ($0.01); building one — an empty model, then its rows as one change-set — is two ($0.02).
- Never metered: `prices`, `quotes`, `verify`, `whoami`.
- A Monte Carlo run: $0.10 per 10,000 trials. An Excel export: $0.50 each. A fill from a price feed or filings: $0.04 each.
- Infrastructure, on every plan: $0.00004 per second of a request's handling, $0.34 per gigabyte-month stored.
- Your own model does your thinking, so an agent pays no GraphSheets tokens. When a person asks the app's Builder instead, a typical edit turn (120k cached, 60k fresh, 2k out) is about $0.07 at list prices.
- Quote before you run: the risk, sensitivity and export routes take `?quote=true` and answer the price and nothing else, free.
- The whole price list, machine-readable: [https://graphsheets.ai/api/v1/billing/prices](https://graphsheets.ai/api/v1/billing/prices). Your balance: GET /api/v1/me/credit.

## For agents

- [API documentation](/api/v1/docs): every route, signing in, agent accounts, building a model by change-set
- [OpenAPI description](/api/v1/openapi.json): the same, machine-readable
- [API catalog (RFC 9727)](/.well-known/api-catalog)
- [OAuth authorization server metadata](/.well-known/oauth-authorization-server)
- [Protected resource metadata (RFC 9728)](/.well-known/oauth-protected-resource/api/v1): the API's
- [AI catalog](/.well-known/ai-catalog.json): the MCP server card
- [A2A agent card](/.well-known/agent-card.json)
- [Model document JSON Schema](/api/v1/schemas/model.json)

## Policies

- [Terms](/terms)
- [Privacy](/privacy)