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 as of May 21, 2026. Most endpoints documented below are in production; some are marked as beta.

Authentication

All requests require a Bearer token in the Authorization header. Get your API key from dcslabs.ai/memory after signup.

Authorization: Bearer dcs_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key types

dcs_sk_live_* are production keys, full access. dcs_sk_test_* are test-mode keys (no real charges, separate data). Never commit your live key to git — see the security guidelines.

Quickstart

Three lines from zero to your first signed memory write:

# 1. Get an API key from dcslabs.ai/memory (free tier, no card required)
# 2. Mint an Agent SBT from dcslabs.ai/mint (free for first 1K builders)
# 3. Store your first signed memory:

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

Rate limits

Tier	Requests/min	Notes
Free	60	Hard cap. 429 on exceed.
Builder	600	$29/mo subscription required.
Sovereign	custom	Negotiated per MSA.

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):
{
  "memory_id":      "mem_a83f12cd",
  "receipt_id":     "r2_a83f12cd",
  "embedding_dim":  1536,
  "signed":         true,
  "stored_at":      "2026-05-21T15:42:08.123Z"
}

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",
  "top_k":     3,
  "threshold": 0.3
}

Response (200):
{
  "results": [
    {
      "memory_id": "mem_a83f12cd",
      "content":   "User prefers vegetarian food, lives in Mumbai",
      "cosine_similarity": 0.524,
      "receipt_id": "r2_a83f12cd"
    }
  ]
}

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

POST /v1/sbt/mint admin

Mint a new Agent SBT on Base mainnet. Admin endpoint — requires elevated permissions. End users mint via the public funnel at dcslabs.ai/mint.

GET /v1/agents/:agent_id

Fetch agent metadata including on-chain identity, public key, and signing history summary.

GET /v1/agents?owner=0x...&page=1

List agents owned by a specific wallet address. Paginated.

Agent Treasury

GET /v1/economy/balance?agent_id=0001

Get the USDC balance held by an agent's Treasury wallet on Base mainnet.

POST /v1/economy/settle

Settle a USDC transaction between two agents. Treasury automatically deducts the 2.5% fee. Settlement happens on-chain; returns the Basescan tx hash.

GET /v1/economy/history?agent_id=0001

Transaction history for an agent. Includes fee paid per transaction, counterparties, and tx hashes.

Error codes

Code	Status	Meaning
invalid_auth	401	API key missing, malformed, or revoked.
insufficient_permissions	403	API key valid but lacks permission for this endpoint.
not_found	404	Requested resource doesn't exist.
rate_limit_exceeded	429	Too many requests. Check `Retry-After` header.
validation_error	400	Request body failed schema validation. See `details`.
signature_invalid	422	R+2 signature on submitted content failed verification.
chain_broken	422	`prev_receipt_cid` doesn't match the agent's actual chain head.
insufficient_funds	402	Treasury balance too low to complete settlement.
internal_error	500	Server-side error. Retry with backoff. Report at [email protected] if persistent.

HTTP status codes

The API follows REST conventions: 2xx for success, 4xx for client errors, 5xx for server errors. Every error response includes a JSON body with error_code and message fields.

SDKs & tooling

npm: @trdnetwork/mcp-server — reference MCP server
npm: @trdnetwork/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]