DCS Labs API

REST API for the DCS Labs agent infrastructure: Sovereign Memory, Agent Treasury, on-chain Identity, and R+2 receipt verification. All endpoints return JSON. All requests are signed.

Base URL: https://api.dcslabs.ai/v1

OpenAPI spec: /docs/openapi.yaml (machine-readable)

Status: Live in production (Supabase-backed, custom domain + SSL). Memory, receipts, agents, economy and auth endpoints are live; embeddings use text-embedding-3-small (1536-dim). Items marked roadmap below are not yet deployed.

Get an API key

Call the public signup endpoint to receive a free-tier key (shown once). No card required.

POST /v1/auth/signup  (public)

curl -X POST https://api.dcslabs.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

Response (200):
{ "ok": true, "api_key": "dcsl_…", "tier": "free",
  "note": "store this key now — it is not shown again" }

Authentication

Protected requests require a Bearer token in the Authorization header. Keys are stored only as salted hashes; treat your key as a secret and never commit it to git — see the security guidelines.

Authorization: Bearer dcsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quickstart

From zero to your first signed memory write:

# 1. Get a free-tier key (POST /v1/auth/signup, above)
# 2. Store your first signed memory:

curl -X POST https://api.dcslabs.ai/v1/memory/store \
  -H "Authorization: Bearer dcsl_..." \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "0001", "content": "hello world" }'

Rate limits

Sovereign Memory

POST /v1/memory/store

Store a memory write. Produces a signed R+2 receipt. Returns the memory_id and receipt_id.

Request body:
{
  "agent_id": "0001",
  "content":  "User prefers vegetarian food, lives in Mumbai",
  "tags":     ["preferences", "personal"],
  "metadata": { "source": "user_settings" }
}

Response (200):
{
  "ok":              true,
  "memory_id":      "<uuid>",
  "receipt_id":     "sha256:…",
  "receipt":        { /* full signed R+2 receipt */ },
  "embedding_model": "text-embedding-3-small",
  "embedding_dim":  1536
}

POST /v1/memory/search

Semantic recall over an agent's memory by cosine similarity. Returns top-k matches.

Request body:
{
  "agent_id":  "0001",
  "query":     "what does this person like to eat",
  "k":         3
}

Response (200):
{
  "ok": true,
  "results": [
    {
      "memory_id": "<uuid>",
      "content":   "User prefers vegetarian food, lives in Mumbai",
      "similarity": 0.83,
      "receipt_id": "sha256:…"
    }
  ]
}

GET /v1/memory/export?agent_id=0001

Export all memory for an agent as a stream of signed R+2 receipts. Useful for backup, regulatory audit export, or migration to another DCS-compatible service.

DELETE /v1/memory/:memory_id

Mark a memory as logically deleted. The underlying R+2 receipt remains in the chain (immutable by design) but the content is no longer returned in search results.

Receipts (R+2)

GET /v1/receipts/:receipt_id

Fetch a single R+2 receipt by ID. Public — no auth required, since receipts are designed to be independently verifiable.

POST /v1/receipts/verify

Server-side verification convenience endpoint. Returns the same result as running r2-verify client-side. Use only for testing; production verification should run client-side per the R+2 spec.

GET /v1/receipts/chain?agent_id=0001&from_cid=...

Walk the chain of receipts for an agent. Returns a paginated stream starting from a given CID. Useful for audit export and chain visualization.

Agent Identity

GET /v1/agents/:agent_id

Public identity lookup — returns the agent's slug, display name, public key, and creation time.

GET /v1/agents

List agents in your account. Requires a bearer key.

POST /v1/sbt/mint roadmap

Programmatic minting of an Agent SBT on Base mainnet is on the roadmap. Today, end users mint via the public funnel at dcslabs.ai/mint; the SBT contract is deployed and source-verified on Base.

Agent economy

A credit ledger that lets agents hold balances and settle with each other. Each settlement emits a signed R+2 receipt. On-chain (USDC) settlement is on the roadmap; the endpoints below operate on the internal credit ledger.

GET /v1/economy/balance?agent_id=0001

Net credit balance for an agent (credits in − credits out). Requires a bearer key.

POST /v1/economy/settle

Move credits between agents and emit a receipt. Body: { "from_agent", "to_agent", "amount", "memo" }. Returns tx_id and the receipt_id.

GET /v1/economy/history?agent_id=0001

Settlement history for an agent — counterparties, amounts, memos, and the receipt CID for each entry.

Meta

GET /v1/health · /version · /stats public

/v1/health returns status, version, mode, the issuer public key, and the embeddings model. /v1/stats returns counts (agents, receipts, memories, transactions). Useful for liveness checks and dashboards.

Errors

Errors use standard HTTP status codes with a JSON body of the form { "error": "message" }.

Receipt verification returns { "valid": true|false, "reason": "…", "cid": "sha256:…" } rather than an error for an invalid signature.

SDKs & tooling

• npm: dcslabs-mcp-server — reference MCP server
• npm: dcslabs-r2-verify — reference verifier CLI
• Coming Q3 2026: Python and Go SDKs
• OpenAPI spec: /docs/openapi.yaml

Support

Builder questions: [email protected]
Bug reports: github.com/DCS-LabsAI
Security: [email protected]