# kotobase

> Knowledge Graph BaaS for engineers and enterprises on kotoba (a Datomic-over-IPFS knowledge graph). Build tenant graphs with Datomic/Datalog, SPARQL/Cypher-style query, KG ingest, MCP tools, and durable content-addressed graph hosting over IPFS.

kotobase.net is the edge API. It exposes tenant-scoped knowledge graph BaaS plus standard IPFS pinning. A "pin" is a named commit CID in kotoba's content-addressed quad store. Auth is either a gftd-AUTHN JWT (HTTP `Authorization: Bearer <JWT>`) or a self-signed CACAO (`Authorization: CACAO <base64-cbor>` + `x-kotoba-did`). Identity: did:web:kotobase.net.

## Quick start (IPFS Pinning Service API)

```
ipfs pin remote service add kotobase https://kotobase.net <JWT>
ipfs pin remote add --service=kotobase --name=<name> <cid>
ipfs pin remote ls --service=kotobase
ipfs pin remote rm --service=kotobase --cid=<cid>
```

Retrieve any pinned CID at https://ipfs.gftd.ai/ipfs/<cid>.

## Interfaces

- IPFS Pinning Service API (PSA, https://ipfs.github.io/pinning-services-api-spec/): POST/GET/DELETE https://kotobase.net/pins (+ /pins/{requestid}). Bearer JWT or CACAO auth.
- XRPC: POST https://kotobase.net/xrpc/ai.gftd.apps.kotobase.<method> — pinCreate, pinList, pinDelete, accountCreate, accountStatus, usageGet; datomic.* (Datom/Datalog read), graph.sparql/graph.query (SPARQL/Cypher), kg.query, kg.ingest/kg.ingest_batch.
- MCP (AI agents): https://mcp.gftd.ai/mcp — tools generated from the same lexicons.

## Business model

- Free developer entry for API and graph workflow validation.
- Standard and Pro subscriptions for self-serve graph workspaces, storage quota, pins, KG ingest, and query access.
- Regulated/enterprise contracts for dedicated tenants, read audit, key custody, compliance review, and custom operation.

## Docs

- [Full docs](https://kotobase.net/llms-full.txt): complete API + usage reference in one plain-text file.
- [Using as a pin service](https://github.com/gftdcojp/net-kotobase/blob/main/docs/USING-AS-A-PIN-SERVICE.md): auth, pin, retrieve, query, quotas, curl examples.

## Notes

- Durability: every pinned commit is archived off-site to Backblaze B2 as one CAR object (CAR-on-B2); cold reads served via ranged GET. Scales by commit count, not block count.
- Tenant graph BaaS includes kg.ingest / kg.ingest_batch and the tenant-capability Datom write plane where enabled; operator-only paths remain gated.
- Roadmap: sk_live_* API keys (today auth is gftd-AUTHN JWT or CACAO); PinStatus delegates (swarm multiaddrs).

## Paid API (x402 / USDC)

Per-request content reads are payable in USDC on Base L2 via the x402 protocol
(HTTP 402 Payment Required) — agent-native, no account or subscription needed:

- Endpoint: `GET /x402/ipfs/{cid}` — $0.001 USDC per read.
- Discover: https://kotobase.net/.well-known/x402
- Facilitator + full catalog across services: https://x402.nexus/catalog