1. Verify

   COLOSSEUM_COPILOT_PAT

   is set in the environment. If missing, STOP and tell the user:

   You need a Personal Access Token before using Copilot. Go to https://arena.colosseum.org/copilot to generate one, then set it:

   export COLOSSEUM_COPILOT_PAT="your-token-here"

2. Verify

   COLOSSEUM_COPILOT_API_BASE

   is set. If missing, set the default:

   export COLOSSEUM_COPILOT_API_BASE="https://copilot.colosseum.com/api/v1"

3. Call

   GET /status

   to verify the connection. Expected response:

   { "authenticated": true, "expiresAt": "...", "scope": "..." }

4. If

   "authenticated": true

   , proceed. If 401 or env vars missing, do NOT attempt other API calls — guide the user through steps 1-2.

• Builder Projects: 5,400+ Solana project submissions with tech stack, problem tags, and competitive context
• Crypto Archives: Curated corpus across cypherpunk literature, protocol docs, investor research, and founder essays
• Hackathon Analytics + Clusters: Distribution, comparison, and chronology-aware trend analysis across hackathons and topic groupings
• The Grid + Web Search: Ecosystem product metadata plus real-time competitive landscape checks

1. Set your PAT:
   bash

   export COLOSSEUM_COPILOT_API_BASE="https://copilot.colosseum.com/api/v1"
   export COLOSSEUM_COPILOT_PAT="YOUR_PAT"

   Get a PAT: Go to https://arena.colosseum.org/copilot and generate a token
2. Run your first search:
   bash

   curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/projects" \
     -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
     -H "Content-Type: application/json" \
     -d '{"query": "privacy wallet for stablecoin users", "limit": 5}'

3. See results - project names, slugs, similarity scores, problem/tech tags

• Researching a crypto/blockchain startup idea
• Evaluating market gaps in the Solana ecosystem
• Grounding ideas in historical crypto literature
• Analyzing builder project trends and competitive landscape
• Researching existing players and finding differentiation angles

• Use the API endpoints below with enough targeted calls to satisfy the evidence floor for the query type
• Cite sources inline (project slugs, archive titles, URLs)
• Keep responses concise — bullet points, not essays
• When the topic warrants deeper analysis, offer: "Want me to do a full deep-dive on this?"
• No meta-commentary about your process ("Now let me search...", "I'll check...")

search/projects

search/archives

These are evidence-type floors, not call budgets. Use as many calls as needed to meet the floor with high-confidence citations.

In deep-dive mode, the verification checklist in

workflow-deep.md

Step 5 supersedes these floors with more granular coverage requirements.

• Archive integration rule: For any non-trivial question (anything beyond a simple one-list retrieval), run at least one

  search/archives

  query and cite at least one archive source in the answer.
• Accelerator/winner portfolio checks: For "what has been tried", "who is building this", "is this crowded/saturated", or similar prompts, run targeted project searches with

  filters: { "acceleratorOnly": true }

  and

  filters: { "winnersOnly": true }

  , then reflect both outcomes in the answer.
• Freshness and temporal anchoring: Use

  hackathon.startDate

  from

  /filters

  ,

  /search/projects

  , and

  /projects/by-slug/:slug

  to order hackathons chronologically; never infer chronology from names or memory. When citing hackathons, include month/year inline (and accelerator cohort like C1/C2/C4 when relevant). For evaluative judgments, label the claim with

  As of YYYY-MM-DD

  .
• Entity coverage check: If the user names specific companies, protocols, papers, or products, run direct searches for each named entity and explicitly address each one in the answer (found, not found, or tangential).
• Landscape check: Never claim "nobody has done this" or "no existing players" unless an accelerator portfolio check (

  acceleratorOnly

  ) was executed and reported. If accelerator overlap exists, surface those builders as useful reference points and potential sources of inspiration. Always qualify landscape assessments with "based on the available data" or "as far as we can tell from the corpus." Copilot's knowledge is bounded by its data sources — never present absence of evidence as evidence of absence.

For the full 8-step deep research workflow, see

references/workflow-deep.md

• Builder Projects (5,400+): Solana project submissions with tech stack, problem/solution tags, verticals, and competitive context
• Crypto Archives: Curated corpus spanning cypherpunk literature, protocol docs, investor research (Paradigm, a16z, Multicoin), founder essays (Paul Graham), Solana protocol docs (Jupiter, Orca, Drift), Nakamoto Institute heritage collection, and foundational crypto texts
• Hackathon Analytics + Chronology: Analyze and compare hackathon projects across dimensions; canonical hackathon dates are available via

  hackathon.startDate

• Clusters: Topic groupings across the project corpus
• The Grid: Ecosystem metadata (products/entities/assets) via direct GraphQL (6,300+ products across all ecosystems, ~3,000 roots)
• Web Search: Real-time competitive landscape via your runtime's search tools
• Source Suggestions: Users can suggest new sources for the archive via

  POST /source-suggestions

  (5 req/hr). See

  references/api-reference.md

  for details

Authorization: Bearer <COPILOT_PAT>

• Do not commit PATs or paste them into public logs
• PATs are long-lived (expected ~90 days); rotate by issuing a new one
• Default API base is

  https://copilot.colosseum.com/api/v1

  ; override

  COLOSSEUM_COPILOT_API_BASE

  to target a different environment

/status

/search/projects

/search/archives

/projects/by-slug/:slug

/archives/:documentId

/analyze

/compare

/clusters/:key

/filters

/source-suggestions

/feedback

For full endpoint docs, curl examples, and query tips:

references/api-reference.md

For Grid GraphQL recipes and product type slugs:

references/grid-recipes.md

• Bullet points with inline citations (project slugs, archive titles)
• Concise answers (typically 5-15 bullets)
• Offer deep-dive when warranted

1. Similar Projects (5-8 bullets)
2. Archive Insights (3-5 bullets)
3. Current Landscape (per research angle)
4. Key Insights (patterns, gaps, trends)
5. Opportunities and Gaps
6. Deep Dive: Top Opportunity (market landscape, problem, revenue model, GTM, founder-market fit, why crypto/Solana, risks)

• API returns unexpected or low-quality results for a reasonable query
• A search returns no results when you expected matches
• You encounter an error that isn't covered by standard error handling
• You have a suggestion for improving the API or archive corpus

curl -X POST "$COLOSSEUM_COPILOT_API_BASE/feedback" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "quality",
    "message": "Search for DePIN projects returned only 2 results, expected more coverage",
    "severity": "medium",
    "context": { "query": "DePIN infrastructure", "endpoint": "/search/projects", "resultCount": 2 }
  }'

error

quality

suggestion

other

low

medium

high

critical

• Empty project results: Broaden query, remove filters
• Empty archive results: Search auto-cascades (vector → chunk text → doc text) before returning empty. If still empty, try conceptual synonyms, keep queries to 3-6 keywords
• 429 Too Many Requests: Back off, max 2 concurrent requests
• API unavailable: Note in report and proceed with available data
• Auth error: Check PAT at https://arena.colosseum.org/copilot

• workflow-deep.md — detailed 8-step research process
• api-reference.md — all endpoints, rate limits, query tips
• grid-recipes.md — GraphQL queries and product type slugs

• The Grid docs: https://docs.thegrid.id
• The Grid Explorer: https://raw.githubusercontent.com/The-Grid-Data/Explorer/main/README.md