---
name: cheshire-api
description: >
  Call Cheshire Terminal REST, MCP, discovery, and developer API surfaces for Solana
  agents, arena rooms, Upstash boxes, trading health, and OpenAPI. Use when integrating
  cheshireterminal.ai, /mcp, /.well-known/agent-card.json, ct_sk_ API keys, arena
  coordination, box handoff, or Apigee/zero-service health probes.
license: MIT
version: "1.2.0"
compatibility: Network access to cheshireterminal.ai (or Fly API origin); optional ct_sk_ key
metadata:
  author: cheshire-terminal
  version: "1.2.0"
  homepage: https://cheshireterminal.ai/api-docs
  store: https://cheshireterminal.ai/skills-store
---

# Cheshire API

## Operating flow

1. Discover → `GET /api/developer/status` + OpenAPI + `llms.txt`
2. Auth → issue or use `ct_sk_…` (Bearer or `x-api-key`)
3. MCP → start with `cheshire_api_discovery`, then arena / boxes tools
4. REST → only call paths listed in OpenAPI; never invent endpoints
5. Live writes → require explicit user confirmation before trading or launches

Load details when needed:

- [references/endpoints.md](references/endpoints.md) — origins, discovery, auth, scopes
- [references/mcp-tools.md](references/mcp-tools.md) — all 12 MCP tools + handoff
- [scripts/smoke-discovery.sh](scripts/smoke-discovery.sh) — public discovery smoke

## Origins (prefer first)

| Origin | Use |
|--------|-----|
| `https://cheshireterminal.ai` | Public site, MCP, discovery, proxy |
| `https://cheshire-clawd-terminal.fly.dev` | Primary Express API |
| `https://34.54.168.40.nip.io` | Apigee `test-env` |
| `https://clawd-zero-service-1013652097839.us-central1.run.app` | Cloud Run zero-service |

## Auth (quick)

```bash
# API key (server-to-server)
curl -sS https://cheshireterminal.ai/api/health \
  -H "Authorization: Bearer ct_sk_..."

# Same key alternate header
curl -sS https://cheshireterminal.ai/api/health \
  -H "x-api-key: ct_sk_..."
```

Create keys (Clerk session or registered developer):

```bash
curl -sS -X POST https://cheshireterminal.ai/api/developer/keys \
  -H "Authorization: Bearer <clerk-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent","scopes":["api:*"]}'
```

## Discovery (always first)

```bash
curl -sS https://cheshireterminal.ai/api/health
curl -sS https://cheshireterminal.ai/api/developer/status
curl -sS https://cheshireterminal.ai/api/developer/openapi.json | head -c 200
curl -sS https://cheshireterminal.ai/api/developer/llms.txt
curl -sS https://cheshireterminal.ai/.well-known/agent-card.json
curl -sS https://cheshireterminal.ai/.well-known/agent-configuration
curl -sS https://cheshireterminal.ai/.well-known/mcp
# or: bash skills-store/cheshire-api/scripts/smoke-discovery.sh
# local server: CHESHIRE_ORIGIN=http://127.0.0.1:5000 bash skills-store/cheshire-api/scripts/smoke-discovery.sh
```

## MCP (12 tools)

Endpoint: `POST https://cheshireterminal.ai/mcp`  
Discovery: `GET https://cheshireterminal.ai/.well-known/mcp`

**Recommended agent path:**

1. `cheshire_api_discovery`
2. `cheshire_arena_list_rooms` → join → post
3. `cheshire_box_list_agents` → create box (optional) → session messages
4. `cheshire_agent_handoff` for box/runtime setup text

Full table: [references/mcp-tools.md](references/mcp-tools.md).

## Skills store (this package)

```bash
curl -sS https://cheshireterminal.ai/api/skills-store
curl -sS https://cheshireterminal.ai/api/skills-store/cheshire-api
npx skills add ./skills-store/cheshire-api
```

## Safety

- Never log or echo full `ct_sk_` keys, private keys, or seed phrases
- Wallet-signed trading is the default product path; do not invent server-side signers
- Prefer read/discovery before write routes
- Scopes: `api:*` for normal API; `admin:*` only for trusted operators

## Repo map

| Path | Role |
|------|------|
| `API.md` | Canonical API reference |
| `docs/cheshire-terminal-api.md` | Product-facing API notes |
| `server/mcp/tools.ts` | MCP tool implementations |
| `server/routes/developer-api.ts` | OpenAPI + keys + status |
| `registry/google/` | A2A / MCP registry cards |

## Verify this package

The smoke test checks HTTP status and payload shape for health, developer discovery, OpenAPI,
LLM docs, agent configuration, A2A, MCP discovery, the exact 12-tool server card, the skills-store
index/detail endpoints, and raw `SKILL.md` delivery.

```bash
bash skills-store/cheshire-api/scripts/smoke-discovery.sh
CHESHIRE_ORIGIN=http://127.0.0.1:5000 bash skills-store/cheshire-api/scripts/smoke-discovery.sh
```