Colosseum Copilot

Colosseum Copilot

Colosseum Copilot is a research API for startup opportunity discovery in crypto and Solana, with support for suggesting new archive sources.

Version Check

This skill is version 1.2.1. After your first API call, check the X-Copilot-Skill-Version response header. If the header value is higher than 1.2.1, tell the user: "A newer version of the Copilot skill is available (vX.X.X). Update with: npx skills add ColosseumOrg/colosseum-copilot"

Pre-Flight Auth Check (REQUIRED)

You MUST complete this check before making any other API call. Do not skip this step.

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

Quickstart (90 seconds to first result)

1. Set your PAT:

   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:

   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

When To Use

Use this skill when:

• 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

How It Works

Mode 1 — Conversational (default): Answer questions with targeted API calls and evidence coverage matched to query type. Cite sources inline, keep responses concise, and offer to do a full deep-dive when the topic warrants it — never auto-trigger it.

Mode 2 — Deep Dive (explicit opt-in): Full 8-step workflow from references/workflow-deep.md. Only activates when user explicitly says "vet this idea", "deep dive", "full analysis", "validate this", "is X worth building?", "should I build X?", or accepts your offer to go deeper.

Conversational Guidelines

• 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...")

Evidence Floors (Conversational Mode)

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.

Conversational Quality Checks (Required)

• 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

Data Sources

• 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

Hackathon Chronology

GET /filters returns hackathons[].startDate and orders hackathons[] chronologically (oldest first).

Auth

All endpoints require Authorization: Bearer <COPILOT_PAT>. Treat the PAT like a password.

• 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

Key Endpoints (Quick Reference)

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

Output Contract

Conversational Mode

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

Deep Dive Mode

Reports follow this structure: 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)

Key rules: bullet points not tables, include project slugs, evidence-based not speculative, cite sources inline. No separate "Sources" section — cite inline only.

Feedback

When you encounter errors, unexpected results, or have suggestions for improving the Copilot experience, report them via the feedback endpoint. This helps the Colosseum team identify and fix issues.

When to send feedback:

• 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 }
  }'

Categories: error, quality, suggestion, other. Severity: low, medium, high, critical. Rate limited to 10 requests per hour.

Error Handling

All errors return { "error": "<message>", "code": "<ERROR_CODE>", "retryable": <boolean> }. See api-reference.md for the full error code table.

• 400 `INVALID_JSON`: Fix the request body JSON syntax and retry
• 400 `INVALID_QUERY`: Fix query params (check field names, value ranges, unknown fields)
• 413 `PAYLOAD_TOO_LARGE`: Reduce request body size (1 MB limit)
• 429 `RATE_LIMITED`: Back off per the Retry-After header, max 2 concurrent requests
• 401 `UNAUTHORIZED`: Check PAT at https://arena.colosseum.org/copilot
• 5xx errors: Note in report and proceed with available data. Include requestId from the response when reporting issues.
• 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

References

• 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

Attribution

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

API Reference

API Reference

Rate Limits

All limits are per-user (keyed by PAT identity). Exceeding a limit returns 429 with "code": "RATE_LIMITED" and "retryable": true.

Tip: The 2-concurrent limit is enforced server-side. Most agent runtimes serialize overflow automatically — submit all your calls and they'll execute in order. If you get repeated 429s, reduce to sequential calls.

Fail-closed: If the concurrency limiter is temporarily unavailable, the API fails closed with a retryable 5xx rather than allowing unlimited concurrency. This is transient — retry after a brief delay.

Endpoints

Unless noted, all requests include:

-H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

GET /filters

Fetch available filters (hackathons, tracks, tags, clusters). Use to translate hackathon or track names into valid slugs/keys and to get canonical hackathon startDate values for chronology-sensitive answers.

curl "$COLOSSEUM_COPILOT_API_BASE/filters" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

Response includes:

• tracks[]: { key, name, hackathonSlug, projectCount }
• hackathons[]: { slug, name, startDate, projectCount, winnerCount } — ordered chronologically (oldest first)
• acceleratorBatches[]: { key, name, companyCount }
• prizeTypes[]: string array of prize category names
• prizePlacements[]: integer array of placement ranks
• problemTags[]: { tag, count } — top 25 by frequency
• solutionTags[]: { tag, count }
• primitives[]: { tag, count }
• techStack[]: { tag, count }
• targetUsers[]: { tag, count }
• clusters[]: { key, label, projectCount } — key format v<N>-c<N>
• archiveSources[]: { key, label, documentCount } — use key values in archive sources filter

Use this endpoint to discover valid filter values for search requests.

POST /search/projects

Primary similarity search for hackathon projects.

Recommended defaults:

• limit: 8-12
• includeFacets: false (only use when you need aggregate tags)

curl -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": 10,
    "filters": {
      "winnersOnly": false,
      "acceleratorOnly": false
    }
  }'

Filter parameters (filters object):

Discover valid values for tag/cluster/source filters via GET /filters.

Facets — aggregate tag distributions across the matched set:

• includeFacets (boolean, default false): enable facet computation. Adds overhead — only use when you need aggregate distributions.
• facets (string[], optional): which dimensions to compute. Options: hackathons, tracks, prizes, problemTags, solutionTags, primitives, techStack, clusters. Omit to compute all 8.
• facetTopK (int, 1-20, default 8): max buckets per dimension.

Response includes facets.{dimension}[]: { key, label, count, sampleProjectSlugs[] }.

Note: facets reflect corpus-wide counts scoped to active filters, not just the returned results page.

Diagnostics — pass includeDiagnostics: true to get search debug info:

Response includes diagnostics:

• modeUsed: "vector", "text", "hybrid", or "filters" — which search mode was used
• fallbackUsed: whether text fallback was triggered
• fallbackReason: why fallback occurred (if applicable)
• vectorCandidates: number of vector search candidates
• textCandidates: number of text search candidates
• tagCandidates: number of semantic tag matches
• diversityDropped: results removed by diversity filter
• totalFoundIsEstimate: whether totalFound is an estimate (true for query searches)
• queryExpanded: the expanded query after synonym expansion
• effectiveFilters: the resolved filter values used

Notes:

• query is optional; omit it for filter-only browsing (prefer omission over an empty string).
• limit <= 25. offset applies after ranking/diversity.
• results[]: each result includes hackathon: { name, slug, startDate } alongside project metadata, tracks, links, evidence, prize, and accelerator fields

Score interpretation (projects): Scores reflect hybrid RRF fusion across vector, text, and semantic tag channels — not raw embedding distance. Use relative ranking within a result set (higher = better match) rather than absolute thresholds. When diagnostics.modeUsed is text, scores represent text relevance (static 0.8). When hybrid, scores combine similarity and text rank. Enable includeDiagnostics: true to see which mode produced results.

POST /search/archives

Search archival documents for conceptual precedents. Search auto-cascades through tiers (vector → chunk text → document text) when a tier returns no results, so empty responses only occur when all tiers are exhausted.

Recommended defaults:

• limit: 4-6
• maxChunksPerDoc: 1 for exploratory search, 2 for deep-dive passes
• minSimilarity: 0.2 (default; lower for broader recall, raise for precision)

curl -X POST "$COLOSSEUM_COPILOT_API_BASE/search/archives" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "prediction markets governance",
    "limit": 5,
    "maxChunksPerDoc": 1
  }'

Response includes:

• results[]: { documentId, title, author, source, url, publishedAt, similarity, snippet, chunkIndex }
• searchTier: which search method produced results (vector, chunk_text, or doc_text)
• totalFound: tier-based count for pagination
• totalMatched: FTS corpus match count
• hasMore: whether more results exist (results.length >= limit)

Notes:

• limit <= 10. limit controls the number of documents returned; each document contributes up to maxChunksPerDoc result items, so total items returned can be limit × maxChunksPerDoc.
• offset applies per document (not per chunk).
• minSimilarity (optional, 0–1, default 0.2): minimum cosine similarity for vector retrieval. Lower values increase recall for niche queries.

Search tiers: Archive search auto-cascades through three retrieval tiers: 1. vector — embedding similarity (primary, uses cosine distance) 2. chunk_text — full-text search on indexed chunks 3. doc_text — full-text search on full documents

The searchTier response field indicates which tier produced results. Score interpretation varies by tier: vector scores are cosine similarity (higher = more similar), while text tier scores are FTS rank values.

Intent modes:

• intent: "docs" (default) — single-query vector search, optimized for precision
• intent: "ideation" — multi-query decomposition for broader recall. Automatically sets maxChunksPerDoc >= 3.

Additional parameters:

• maxDocsPerSource (int, 0-10, default 3): cap results from any single source. Set 0 for unlimited.
• minSimilarity (0-1, default 0.2): minimum cosine similarity for vector retrieval. Lower for niche queries.

Limit semantics: limit controls the number of documents returned. Each document can have up to maxChunksPerDoc chunks, so total result items can exceed limit.

Score interpretation (archives): Similarity > 0.4 is a strong topical match. 0.2–0.4 is worth reading but verify relevance. < 0.2 is usually tangential — only include if content is clearly relevant despite low score. Scores vary by query breadth: broad queries ("crypto payments") produce higher peaks than niche queries ("zero-knowledge invoice factoring"). When searchTier is chunk_text or doc_text, the result came from text fallback, not vector similarity — prioritize snippet/title relevance over score magnitude in those cases.

Note: publishedAt can be null for some archive documents (undated sources). Handle this field as nullable in any date-based filtering or display logic.

GET /archives/:documentId

Fetch a paged archive document slice by documentId. Use offset + maxChars to page through the text.

curl "$COLOSSEUM_COPILOT_API_BASE/archives/DOCUMENT_UUID?offset=0&maxChars=8000" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

GET /projects/by-slug/:slug

Fetch full details for a project by slug. Use for 1-2 top results when evidence is insufficient.

curl "$COLOSSEUM_COPILOT_API_BASE/projects/by-slug/your-project-slug" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

Response includes hackathon: { name, slug, startDate } alongside project description, tracks, links, team, prize, repo/media, and semantic tags.

POST /analyze

Summarize tag/track distributions for a hackathon set.

curl -X POST "$COLOSSEUM_COPILOT_API_BASE/analyze" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "cohort": { "hackathons": ["breakout", "radar"], "winnersOnly": true },
    "dimensions": ["tracks", "problemTags"],
    "topK": 5,
    "samplePerBucket": 1
  }'

Response shape:

• totals: { "projects": <number>, "winners": <number> }
• buckets: Object keyed by each requested dimension. Each dimension maps to an array of buckets:

{ "key": "<tag>", "label": "<display name>", "count": <number>, "share": <0-1 fraction>, "sampleProjectSlugs": ["slug1", "slug2"] }

samplePerBucket controls how many sample slugs appear per bucket (default: 2, max: 5).

POST /compare

Compare two hackathon sets across the same dimensions.

curl -X POST "$COLOSSEUM_COPILOT_API_BASE/compare" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "cohortA": { "hackathons": ["breakout", "radar"], "winnersOnly": true },
    "cohortB": { "hackathons": ["breakout", "radar"], "winnersOnly": false },
    "dimensions": ["tracks", "problemTags"],
    "topK": 5
  }'

GET /clusters/:clusterKey

Fetch cluster details by cluster key. Only use when a cluster key is present in results.

curl "$COLOSSEUM_COPILOT_API_BASE/clusters/v1-c12" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

Response includes:

• key: cluster key (e.g., v1-c12)
• label: human-readable cluster name
• summary: LLM-generated cluster description
• projectCount: total projects in cluster
• winnerCount: prize-winning projects
• representativeProjects[]: { slug, name, oneLiner, isWinner } — sample projects
• topTags.problemTags[]: { tag, count } — top problem tags
• topTags.primitives[]: { tag, count }
• topTags.techStack[]: { tag, count }

POST /source-suggestions

Suggest a new source for the archive corpus. Requires auth. Rate limited to 5 requests per hour per user.

curl -X POST "$COLOSSEUM_COPILOT_API_BASE/source-suggestions" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/solana-mev-research",
    "name": "MEV Research Blog",
    "reason": "Great technical analysis of Solana MEV strategies"
  }'

Request parameters:

Response: 201 Created

{ "message": "Thanks! We'll review your suggestion." }

Every submission is reviewed by the team. Approved sources are added to the archive pipeline.

POST /feedback

Report errors, quality issues, or suggestions to help improve the Copilot experience. Rate limited to 10 requests per hour per user.

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

Request parameters:

Response: 201 Created

{ "message": "Feedback received. Thank you." }

High and critical severity feedback is escalated to the team immediately.

Query Tips

Archive search:

• Keep queries to 3-6 focused keywords. Too short (1-2 words) is vague; too long dilutes embedding similarity (e.g., use "prediction markets governance" not "remailers anonymity mix networks privacy routing onion").
• Quality gate: if top results are all pre-2010 and prompt is about modern implementation, re-query with ecosystem-specific terms (Solana, SPL, Anchor, etc.).
• Prefer 3-4 high-quality archive citations over padding to 5 with tangential references.
• maxChunksPerDoc: use 1 for exploratory passes (broad discovery); use 2 for deep-dive passes (Step 7c) when you need richer context from a known-relevant document.
• Archive search auto-cascades (vector → chunk text → doc text) before returning empty. If still empty, try conceptual synonyms (e.g., "prediction markets" -> "futarchy").
• Check searchTier in the response to understand which tier produced results — chunk_text or doc_text means vector similarity was too low for the query.

Project search:

• Natural language queries work well ("privacy wallet for stablecoin users").
• Use filters to narrow by hackathon, track, or tech stack rather than stuffing filter terms into the query.
• includeFacets: true adds overhead — only enable when you need aggregate tag distributions.
• diversify: false — use this when doing a focused investigation of a specific niche, incumbent, or competitor landscape (e.g., "show me all DEX aggregators"). This disables cross-hackathon diversity ranking and returns results purely by similarity score. Only use for narrow deep-dives, not for broad discovery where cross-hackathon coverage matters.

Hackathon analysis:

• clusters, problemTags, techStack: these dimensions exist in the schema but may not be populated for all hackathon sets. If a dimension returns empty, try tracks or problemTags instead.
• Cross-hackathon compare: use GET /filters hackathons[].startDate for chronology; track keys are per-hackathon, so track-level comparisons work best within the same hackathon (e.g., winners vs. all).

Web Search

Use your runtime's most powerful web search tool (WebSearch, Brave Search, Exa, etc.).

Recommended defaults:

• One query per differentiated angle (2-3 queries typical)
• 5-8 results per query

Suggested query patterns:

• "{idea}" crypto startup funding
• "{idea}" production on Solana
• "{idea}" DAO governance implementation
• "{idea}" research report 2024 2025
• "{idea}" protocol standard specification 2024 2025

Error Handling

All errors return a JSON body with this shape:

{ "error": "<message>", "code": "<ERROR_CODE>", "retryable": <boolean> }

Server errors (5xx) also include a requestId field for log correlation when reporting issues.

Some 5xx responses may use a more specific code derived from the server-side error class instead of INTERNAL_ERROR. Treat any 5xx with retryable: true as transient and include the requestId when reporting issues.

For 429: the Retry-After header indicates seconds to wait. Most agent runtimes serialize overflow automatically.

The Grid — GraphQL Recipes

The Grid (Direct GraphQL)

Schema Overview

• Endpoint: https://beta.node.thegrid.id/graphql
• GraphiQL: https://cloud.hasura.io/public/graphiql?endpoint=https%3A%2F%2Fbeta.node.thegrid.id%2Fgraphql
• Auth: No API key required for public queries. If you have an enterprise key, add -H "x-api-key: <key>".
• Schema hierarchy: roots → products/entities/assets/profileInfos → deployments/contracts
• Data volume: ~6,300 products (all ecosystems), ~3,000 roots, ~2,500 entities
• Operators: _eq, _in, _contains, _like, _gt/_gte/_lt/_lte, _and/_or/_not, _is_null
• No full-text search — _contains and _like are case-insensitive substring matches
• Always check the errors field in JSON responses (GraphQL errors return HTTP 200)

Product Type Slug Cheat Sheet

See the topic → slug mapping table and full slug list in Step 2e in workflow-deep.md. Key verticals for quick reference:

• DeFi: decentralised_exchange (207), decentralised_borrowing_and_lending (114), yield_aggregator (113), dex_aggregator (81), liquid_staking (82), derivatives (46)
• Payments: merchant_payment_gateway (159), on_off_ramp (145), payments_infrastructure_and_orchestration (136)
• Infrastructure: developer_tooling (599), block_explorer (113), onchain_data_api (100), rpc_provider (44), oracle (46)
• AI: ai_agent (104), ai_agent_platform (77), ai_agent_framework (27)
• Other: wallet (331), game (131), bridge (101), depin (80), stablecoin_issuance (71), nft_marketplace (68)

Query Recipes

1. Vertical Search (category + Solana scoping) — default starting point

Filter by productType slugs with triple-OR Solana scoping (deployment, supports-product, profile tag) and dead-product exclusion:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query VerticalSearch($typeSlugs:[String!]!,$chain:String!,$tag:String!,$dead:[String!]!,$limit:Int!){products(limit:$limit,where:{_and:[{productType:{slug:{_in:$typeSlugs}}},{_or:[{productDeployments:{smartContractDeployment:{deployedOnProduct:{name:{_eq:$chain}}}}},{supportsProducts:{supportsProduct:{name:{_eq:$chain}}}},{root:{profileTags:{tag:{slug:{_eq:$tag}}}}}]},{_not:{productStatus:{slug:{_in:$dead}}}}]}){id name productType{slug name}productStatus{slug}root{slug urlMain gridRank{score}}}}","variables":{"typeSlugs":["decentralised_exchange","dex_aggregator"],"chain":"Solana Mainnet","tag":"solana","dead":["discontinued","support_ended"],"limit":25}}
QUERY

2. Broad Keyword Search (name/description/slug/entity recall) — fallback

Searches across product name, description, root slug, and entity names. Use when the topic doesn't map cleanly to product type slugs:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query BroadKeyword($q:String!,$dead:[String!]!,$limit:Int!){products(limit:$limit,where:{_and:[{_or:[{name:{_contains:$q}},{description:{_contains:$q}},{root:{slug:{_contains:$q}}},{root:{entities:{_or:[{name:{_contains:$q}},{tradeName:{_contains:$q}}]}}}]},{_not:{productStatus:{slug:{_in:$dead}}}}]}){id name description productType{slug name}productStatus{slug}root{slug urlMain}}}","variables":{"q":"lending","dead":["discontinued","support_ended"],"limit":15}}
QUERY

3. Root Profile Expansion (deep enrichment) — for Step 6 incumbent analysis

Once you have a root slug, pull descriptions, tags, socials, URLs, and products:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query RootProfile($slug:String!){roots(limit:1,where:{slug:{_eq:$slug}}){id slug urlMain gridRank{score}profileInfos{tagLine descriptionShort descriptionLong}urls{url urlType{slug name}}socials{name socialType{slug name}urls{url}}products(limit:10,order_by:{name:Asc}){id name productType{slug name}productStatus{slug name}}profileTags(limit:10){tag{slug name}}}}","variables":{"slug":"Jupiter"}}
QUERY

4. Saturation Aggregate (product count + distinct root count) — for gap validation

Count total products and distinct roots matching a category filter. Use to ground "how crowded is this space?" claims:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query Saturation($typeSlugs:[String!]!,$tag:String!,$dead:[String!]!){productsAggregate(filter_input:{where:{_and:[{productType:{slug:{_in:$typeSlugs}}},{root:{profileTags:{tag:{slug:{_eq:$tag}}}}},{_not:{productStatus:{slug:{_in:$dead}}}}]}}){_count rootId{_count_distinct}}}","variables":{"typeSlugs":["decentralised_exchange","dex_aggregator"],"tag":"solana","dead":["discontinued","support_ended"]}}
QUERY

Solana Ecosystem Filtering

Three approaches with different coverage/precision trade-offs:

• Tag-based (broadest): root: { profileTags: { tag: { slug: { _eq: "solana" } } } }
• Deployment-based (highest precision, narrower coverage): productDeployments: { smartContractDeployment: { deployedOnProduct: { name: { _eq: "Solana Mainnet" } } } }
• CAIP-2 attribute (narrow, limited coverage): attributes: { attributeType: { slug: { _eq: "chain_id_caip2" } }, value: { _contains: "solana" } }

The Vertical Search recipe above uses triple-OR across all three for maximum recall.

For additional Grid query recipes (asset mapping, token relationships, deployment graphs, corporate structure), see the-grid-skill.md.

The Grid (Deep Research)

What The Grid Is

The Grid provides ecosystem metadata you can query via GraphQL: roots (projects/organizations), products, assets/tokens, entities, tags, smart-contract deployments, and relationship graphs (product supports-product edges, root relationship edges).

Data volume: ~6,300 products (all ecosystems), ~3,000 roots, ~2,500 entities, ~1,700 assets, ~7,300 profile tags, ~3,900 smart contract deployments.

Endpoints

Default endpoint:

export THEGRID_GRAPHQL_ENDPOINT="https://beta.node.thegrid.id/graphql"

GraphiQL (default endpoint):

• https://cloud.hasura.io/public/graphiql?endpoint=https%3A%2F%2Fbeta.node.thegrid.id%2Fgraphql

Docs:

• https://docs.thegrid.id/using-the-api-11

Auth (Optional)

Most dataset queries work without an API key. The Grid docs state: "There is currently no key needed":

• https://docs.thegrid.id/getting-an-api-key-9

If you have a key (enterprise / future), send it as an HTTP header:

export THEGRID_API_KEY="YOUR_KEY"

Then add:

x-api-key: $THEGRID_API_KEY

Note: some advanced endpoints can also require an xApiKey GraphQL argument (example shown later).

Ways To Query (Pick One)

• GraphiQL (manual exploration): https://cloud.hasura.io/public/graphiql?endpoint=https%3A%2F%2Fbeta.node.thegrid.id%2Fgraphql
• cURL (primary): copy/paste templates below
• Node.js (built-in fetch): minimal snippet below
• Python (requests): minimal snippet below

Node.js (built-in fetch):

const endpoint =
  process.env.THEGRID_GRAPHQL_ENDPOINT ?? 'https://beta.node.thegrid.id/graphql';

const headers = { 'content-type': 'application/json' };
if (process.env.THEGRID_API_KEY) headers['x-api-key'] = process.env.THEGRID_API_KEY;

const payload = {
  query:
    'query($q:String!,$limit:Int!){products(limit:$limit,where:{_or:[{name:{_contains:$q}},{description:{_contains:$q}}]}){id name root{slug urlMain}}}',
  variables: { q: 'jupiter', limit: 5 },
};

const res = await fetch(endpoint, {
  method: 'POST',
  headers,
  body: JSON.stringify(payload),
});

const json = await res.json();
if (json.errors?.length) throw new Error(JSON.stringify(json.errors));
console.log(json.data);

Python (requests):

import os
import requests

endpoint = os.environ.get("THEGRID_GRAPHQL_ENDPOINT", "https://beta.node.thegrid.id/graphql")
headers = {"content-type": "application/json"}

api_key = os.environ.get("THEGRID_API_KEY")
if api_key:
    headers["x-api-key"] = api_key

payload = {
    "query": "query($q:String!,$limit:Int!){products(limit:$limit,where:{_or:[{name:{_contains:$q}},{description:{_contains:$q}}]}){id name root{slug urlMain}}}",
    "variables": {"q": "jupiter", "limit": 5},
}

res = requests.post(endpoint, json=payload, headers=headers, timeout=30)
res.raise_for_status()
data = res.json()
print({"data": data.get("data"), "errors": data.get("errors")})

cURL Template (Copy/Paste)

GraphQL errors often return with HTTP 200. Always check the errors field in the JSON response.

set -euo pipefail

export THEGRID_GRAPHQL_ENDPOINT="https://beta.node.thegrid.id/graphql"
# Optional:
# export THEGRID_API_KEY="YOUR_KEY"

H=(-H 'content-type: application/json')
if [ -n "${THEGRID_API_KEY:-}" ]; then
  H+=(-H "x-api-key: $THEGRID_API_KEY")
fi

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{
  "query": "query($q:String!,$limit:Int!){products(limit:$limit,where:{_or:[{name:{_contains:$q}},{description:{_contains:$q}}]}){id name root{slug urlMain}}}",
  "variables": { "q": "jupiter", "limit": 5 }
}
JSON

Critical Syntax Notes (Don't Get Stuck)

• String filters: use _contains (simple substring) and _like (pattern match). There is no _ilike or _regex. Both _contains and _like are case-insensitive in practice.
• Full operator set: _eq, _in, _contains, _like, _gt/_gte/_lt/_lte, _and/_or/_not, _is_null. No full-text search or scoring operator exists.
• Ordering enum values are Asc / Desc (capitalized).
• Keep limit small (5 to 25). Use offset for pagination.
• Start with small selection sets; expand by id (e.g. rootsById, productsById, assetsById) once you find promising candidates.
• Always exclude dead products in incumbent searches: _not: { productStatus: { slug: { _in: ["discontinued", "support_ended"] } } }.
• Aggregate queries use filter_input: { where: {...} } (not where directly).

Schema Discovery (Introspection)

If a query fails with "no such field", use introspection to discover the right field names and filter inputs.

List fields for a type:

query FieldsForRoots {
  __type(name: "Roots") {
    fields { name }
  }
}

List filter input fields for a bool exp type:

query RootRelationshipFilters {
  __type(name: "RootRelationshipsBoolExp") {
    inputFields { name }
  }
}

Product Type Slug Taxonomy

The strongest precision lever for incumbent discovery is filtering by productType.slug. There are 115 product type slugs total. Map your research topic to slugs using this guide:

Top 30 by count: developer_tooling (599), wallet (331), decentralised_exchange (207), centralised_exchange (182), financial_services_platform (174), merchant_payment_gateway (159), on_off_ramp (145), l1 (144), payments_infrastructure_and_orchestration (136), game (131), decentralised_borrowing_and_lending (114), yield_aggregator (113), block_explorer (113), ai_agent (104), bridge (101), onchain_data_api (100), dex_aggregator (81), depin (80), ai_agent_platform (77), cross_chain_infrastructure (73), stablecoin_issuance (71), nft_marketplace (68), peer_to_peer_and_remittance (67), decentralised_identity (55), oracle (46), derivatives (46), embedded_wallet (46), rpc_provider (44), prediction_markets (28), ai_agent_framework (27). Query productTypes for the full list.

Solana Ecosystem Filtering

Three approaches with different coverage/precision trade-offs. For maximum recall, combine all three with `_or` (see Vertical Search recipe below).

Option A: Profile tags (broadest — recommended default)

where: {
  root: {
    profileTags: {
      tag: { slug: { _eq: "solana" } }
    }
  }
}

Option B: Smart contract deployments (highest precision, narrower coverage)

where: {
  productDeployments: {
    smartContractDeployment: {
      deployedOnProduct: { name: { _eq: "Solana Mainnet" } }
    }
  }
}

Option C: CAIP-2 attribute (narrow, limited coverage — use as supplement)

where: {
  attributes: {
    attributeType: { slug: { _eq: "chain_id_caip2" } }
    value: { _contains: "solana" }
  }
}

Other ecosystem tags with profile coverage: ethereum (1,371), tether (1,337), bitcoin (599), tron (398), starknet (279), ai (180).

High-Value Query Recipes (Idea Research)

Each recipe includes:

• When to use it
• A complete GraphQL query
• A ready-to-run curl invocation using variables

All curl examples assume you have set THEGRID_GRAPHQL_ENDPOINT and built the H header array as shown in the cURL template above. If you are running a single snippet in isolation, replace "${H[@]}" with -H "content-type: application/json" (and optionally -H "x-api-key: $THEGRID_API_KEY").

Vertical Search (Category + Solana Scoping)

When to use: incumbent search for a specific vertical. This is the highest-precision starting point — map your topic to productType slugs (see taxonomy above) and combine with triple-OR Solana ecosystem scoping for maximum recall.

query VerticalSearch(
  $typeSlugs: [String!]!
  $chain: String!
  $tag: String!
  $dead: [String!]!
  $limit: Int!
) {
  products(
    limit: $limit
    where: {
      _and: [
        { productType: { slug: { _in: $typeSlugs } } }
        {
          _or: [
            { productDeployments: { smartContractDeployment: { deployedOnProduct: { name: { _eq: $chain } } } } }
            { supportsProducts: { supportsProduct: { name: { _eq: $chain } } } }
            { root: { profileTags: { tag: { slug: { _eq: $tag } } } } }
          ]
        }
        { _not: { productStatus: { slug: { _in: $dead } } } }
      ]
    }
  ) {
    id
    name
    productType { slug name }
    productStatus { slug }
    root { slug urlMain gridRank { score } }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query VerticalSearch($typeSlugs:[String!]!,$chain:String!,$tag:String!,$dead:[String!]!,$limit:Int!){products(limit:$limit,where:{_and:[{productType:{slug:{_in:$typeSlugs}}},{_or:[{productDeployments:{smartContractDeployment:{deployedOnProduct:{name:{_eq:$chain}}}}},{supportsProducts:{supportsProduct:{name:{_eq:$chain}}}},{root:{profileTags:{tag:{slug:{_eq:$tag}}}}}]},{_not:{productStatus:{slug:{_in:$dead}}}}]}){id name productType{slug name}productStatus{slug}root{slug urlMain gridRank{score}}}}","variables":{"typeSlugs":["decentralised_exchange","dex_aggregator"],"chain":"Solana Mainnet","tag":"solana","dead":["discontinued","support_ended"],"limit":25}}
JSON

Broad Keyword Search (Multi-Field)

When to use: first-pass recall when the topic doesn't map cleanly to product type slugs. Searches across product name, description, root slug, and entity names with dead-product exclusion.

query BroadKeyword($q: String!, $dead: [String!]!, $limit: Int!) {
  products(
    limit: $limit
    where: {
      _and: [
        {
          _or: [
            { name: { _contains: $q } }
            { description: { _contains: $q } }
            { root: { slug: { _contains: $q } } }
            { root: { entities: { _or: [{ name: { _contains: $q } }, { tradeName: { _contains: $q } }] } } }
          ]
        }
        { _not: { productStatus: { slug: { _in: $dead } } } }
      ]
    }
  ) {
    id
    name
    description
    productType { slug name }
    productStatus { slug }
    root { slug urlMain }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query BroadKeyword($q:String!,$dead:[String!]!,$limit:Int!){products(limit:$limit,where:{_and:[{_or:[{name:{_contains:$q}},{description:{_contains:$q}},{root:{slug:{_contains:$q}}},{root:{entities:{_or:[{name:{_contains:$q}},{tradeName:{_contains:$q}}]}}}]},{_not:{productStatus:{slug:{_in:$dead}}}}]}){id name description productType{slug name}productStatus{slug}root{slug urlMain}}}","variables":{"q":"lending","dead":["discontinued","support_ended"],"limit":15}}
JSON

Keyword Search: Products (Basic)

When to use: quick product lookup by keyword. For incumbent discovery, prefer Vertical Search (category-based) or Broad Keyword Search (multi-field) above.

query SearchProducts($q: String!, $limit: Int!) {
  products(
    limit: $limit
    where: {
      _or: [{ name: { _contains: $q } }, { description: { _contains: $q } }]
    }
  ) {
    id
    name
    description
    launchDate
    productType { slug name }
    productStatus { slug name }
    root { slug urlMain gridRank { score } }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query SearchProducts($q:String!,$limit:Int!){products(limit:$limit,where:{_or:[{name:{_contains:$q}},{description:{_contains:$q}}]}){id name description launchDate productType{slug name} productStatus{slug name} root{slug urlMain gridRank{score}}}}","variables":{"q":"jupiter","limit":5}}
JSON

Keyword Search: Entities

When to use: find organizations/companies (entities) and jump to the related root profile.

query SearchEntities($q: String!, $limit: Int!) {
  entities(
    limit: $limit
    where: { _or: [{ name: { _contains: $q } }, { tradeName: { _contains: $q } }] }
  ) {
    id
    name
    tradeName
    country { name }
    root { slug urlMain }
    urls { url urlType { slug name } }
    socials { name socialType { slug name } urls { url } }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query SearchEntities($q:String!,$limit:Int!){entities(limit:$limit,where:{_or:[{name:{_contains:$q}},{tradeName:{_contains:$q}}]}){id name tradeName country{name} root{slug urlMain} urls{url urlType{slug name}} socials{name socialType{slug name} urls{url}}}}","variables":{"q":"coinbase","limit":5}}
JSON

Expand: Root Profile (Deep)

When to use: once you have a root slug, pull descriptions, socials/urls, and a few products.

query RootProfile($slug: String!) {
  roots(limit: 1, where: { slug: { _eq: $slug } }) {
    id
    slug
    urlMain
    gridRank { score }
    profileInfos {
      tagLine
      descriptionShort
      descriptionLong
      descriptionMarketing
    }
    urls { url urlType { slug name } }
    socials { name socialType { slug name } urls { url } }
    products(
      limit: 10
      order_by: { name: Asc }
      where: { isMainProduct: { _eq: 1 } }
    ) {
      id
      name
      productType { slug name }
      productStatus { slug name }
    }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query RootProfile($slug:String!){roots(limit:1,where:{slug:{_eq:$slug}}){id slug urlMain gridRank{score} profileInfos{tagLine descriptionShort descriptionLong descriptionMarketing} urls{url urlType{slug name}} socials{name socialType{slug name} urls{url}} products(limit:10,order_by:{name:Asc},where:{isMainProduct:{_eq:1}}){id name productType{slug name} productStatus{slug name}}}}","variables":{"slug":"Jupiter"}}
JSON

Top Ecosystems: Rank Leaderboard

When to use: identify category leaders and "default" primitives to benchmark against.

query TopRoots($limit: Int!) {
  roots(limit: $limit, order_by: { gridRank: { score: Desc } }) {
    slug
    urlMain
    gridRank { score }
    profileInfos { tagLine descriptionShort }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query TopRoots($limit:Int!){roots(limit:$limit,order_by:{gridRank:{score:Desc}}){slug urlMain gridRank{score} profileInfos{tagLine descriptionShort}}}","variables":{"limit":10}}
JSON

Tags: Find Relevant Tags + Expand To Roots

When to use: tag-based discovery is often higher-signal than free-text search for ecosystems.

Find tag slugs by keyword:

query SearchTags($q: String!, $limit: Int!) {
  tags(limit: $limit, where: { name: { _contains: $q } }, order_by: { name: Asc }) {
    id
    slug
    name
    tagType { slug name }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query SearchTags($q:String!,$limit:Int!){tags(limit:$limit,where:{name:{_contains:$q}},order_by:{name:Asc}){id slug name tagType{slug name}}}","variables":{"q":"defi","limit":10}}
JSON

Expand a tag slug to top roots (rank-sorted):

query RootsByTag($tag: String!, $limit: Int!) {
  profileTags(
    limit: $limit
    where: { tag: { slug: { _eq: $tag } } }
    order_by: { root: { gridRank: { score: Desc } } }
  ) {
    root { slug urlMain gridRank { score } }
    tag { slug name }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query RootsByTag($tag:String!,$limit:Int!){profileTags(limit:$limit,where:{tag:{slug:{_eq:$tag}}},order_by:{root:{gridRank:{score:Desc}}}){root{slug urlMain gridRank{score}} tag{slug name}}}","variables":{"tag":"defi","limit":10}}
JSON

Solana-Focused Discovery (Approach 1): Chain Attribute (CAIP-2)

When to use: discover chain roots (and chain-specific ecosystems) by standard chain identifiers.

query RootsByAttribute($attrSlug: String!, $needle: String!, $limit: Int!) {
  roots(
    limit: $limit
    where: {
      attributes: {
        attributeType: { slug: { _eq: $attrSlug } }
        value: { _contains: $needle }
      }
    }
  ) {
    slug
    urlMain
    attributes(where: { attributeType: { slug: { _eq: $attrSlug } } }) { value }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query RootsByAttribute($attrSlug:String!,$needle:String!,$limit:Int!){roots(limit:$limit,where:{attributes:{attributeType:{slug:{_eq:$attrSlug}},value:{_contains:$needle}}}){slug urlMain attributes(where:{attributeType:{slug:{_eq:$attrSlug}}}){value}}}","variables":{"attrSlug":"chain_id_caip2","needle":"solana:","limit":10}}
JSON

Solana-Focused Discovery (Approach 2): Smart Contract Deployments

When to use: find products with on-chain deployments on a specific chain.

Step A: find the chain "product id" (example: Solana Mainnet).

query FindChainProduct($q: String!) {
  products(limit: 10, where: { name: { _contains: $q } }) { id name }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query FindChainProduct($q:String!){products(limit:10,where:{name:{_contains:$q}}){id name}}","variables":{"q":"Solana Mainnet"}}
JSON

Step B: filter products deployed on that chain (use the id from Step A; for Solana Mainnet it's commonly 22).

query ProductsDeployedOn($deployedOnId: String!, $limit: Int!) {
  products(
    limit: $limit
    where: {
      productDeployments: {
        smartContractDeployment: { deployedOnId: { _eq: $deployedOnId } }
      }
    }
  ) {
    id
    name
    productType { slug name }
    productStatus { slug name }
    root { slug urlMain }
    productDeployments(limit: 2) {
      smartContractDeployment {
        deployedOnProduct { name }
        smartContracts(limit: 2) { address name }
      }
    }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query ProductsDeployedOn($deployedOnId:String!,$limit:Int!){products(limit:$limit,where:{productDeployments:{smartContractDeployment:{deployedOnId:{_eq:$deployedOnId}}}}){id name productType{slug name} productStatus{slug name} root{slug urlMain} productDeployments(limit:2){smartContractDeployment{deployedOnProduct{name} smartContracts(limit:2){address name}}}}}","variables":{"deployedOnId":"22","limit":10}}
JSON

Solana-Focused Discovery (Approach 3): Profile Tags (Broadest)

When to use: broadest Solana ecosystem discovery; deployment-based is narrower but more precise. This is the recommended default for Solana scoping.

query SolanaByTag($tag: String!, $limit: Int!) {
  products(
    limit: $limit
    where: {
      root: { profileTags: { tag: { slug: { _eq: $tag } } } }
      _not: { productStatus: { slug: { _in: ["discontinued", "support_ended"] } } }
    }
    order_by: { root: { gridRank: { score: Desc } } }
  ) {
    id
    name
    productType { slug name }
    productStatus { slug }
    root { slug urlMain gridRank { score } }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query SolanaByTag($tag:String!,$limit:Int!){products(limit:$limit,where:{root:{profileTags:{tag:{slug:{_eq:$tag}}}},_not:{productStatus:{slug:{_in:[\"discontinued\",\"support_ended\"]}}}},order_by:{root:{gridRank:{score:Desc}}}){id name productType{slug name}productStatus{slug}root{slug urlMain gridRank{score}}}}","variables":{"tag":"solana","limit":25}}
JSON

Integration Graph: Supports Products (Dependencies + Reverse Dependencies)

When to use: map dependencies (infra, RPCs, frameworks) and identify missing primitives.

query ProductSupportGraph($productId: String!) {
  productsById(id: $productId) {
    id
    name
    root { slug urlMain }
    supportsProducts(limit: 25) {
      supportsProduct { id name root { slug urlMain } }
    }
    supportsProductsBySupportsProductId(limit: 25) {
      product { id name root { slug urlMain } }
    }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query ProductSupportGraph($productId:String!){productsById(id:$productId){id name root{slug urlMain} supportsProducts(limit:25){supportsProduct{id name root{slug urlMain}}} supportsProductsBySupportsProductId(limit:25){product{id name root{slug urlMain}}}}}","variables":{"productId":"100"}}
JSON

Asset / Token Mapping: Find By Ticker + Expand Relationships

When to use: link a token to products, distribution platforms, and governance systems.

Find the asset by ticker:

query FindAssetByTicker($ticker: String!) {
  assets(limit: 5, where: { ticker: { _eq: $ticker } }) {
    id
    name
    ticker
    description
    assetType { slug name }
    root { slug urlMain }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query FindAssetByTicker($ticker:String!){assets(limit:5,where:{ticker:{_eq:$ticker}}){id name ticker description assetType{slug name} root{slug urlMain}}}","variables":{"ticker":"DRIFT"}}
JSON

Expand asset relationships:

query AssetRelationships($assetId: String!) {
  assetsById(id: $assetId) {
    id
    name
    ticker
    root { slug urlMain }
    productAssetRelationships(limit: 25) {
      assetSupportType { slug name }
      product { id name root { slug urlMain } }
    }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query AssetRelationships($assetId:String!){assetsById(id:$assetId){id name ticker root{slug urlMain} productAssetRelationships(limit:25){assetSupportType{slug name} product{id name root{slug urlMain}}}}}","variables":{"assetId":"101"}}
JSON

Root Relationship Graph: Corporate / Suite Structure

When to use: discover parent-child relationships like "managed by", "acquired by", "product of".

Step A: resolve a root slug to a root id.

query RootId($slug: String!) {
  roots(limit: 1, where: { slug: { _eq: $slug } }) { id slug urlMain }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query RootId($slug:String!){roots(limit:1,where:{slug:{_eq:$slug}}){id slug urlMain}}","variables":{"slug":"Coinbase"}}
JSON

Step B: fetch relationships by parentRootId (filtering by slug is not supported in the relationship bool exp).

query RootRelationships($rootId: String!, $limit: Int!) {
  rootRelationships(limit: $limit, where: { parentRootId: { _eq: $rootId } }) {
    rootRelationshipType { slug name }
    childRoot { id slug urlMain }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query RootRelationships($rootId:String!,$limit:Int!){rootRelationships(limit:$limit,where:{parentRootId:{_eq:$rootId}}){rootRelationshipType{slug name} childRoot{id slug urlMain}}}","variables":{"rootId":"1125","limit":25}}
JSON

Aggregates: Saturation Signals

When to use: estimate how crowded a space is before you claim a "gap". Use the category-based version for vertical analysis; the keyword version for quick checks.

Category-based (recommended for vertical analysis):

query VerticalSaturation($typeSlugs: [String!]!, $tag: String!, $dead: [String!]!) {
  productsAggregate(
    filter_input: {
      where: {
        _and: [
          { productType: { slug: { _in: $typeSlugs } } }
          { root: { profileTags: { tag: { slug: { _eq: $tag } } } } }
          { _not: { productStatus: { slug: { _in: $dead } } } }
        ]
      }
    }
  ) {
    _count
    rootId { _count_distinct }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query VerticalSaturation($typeSlugs:[String!]!,$tag:String!,$dead:[String!]!){productsAggregate(filter_input:{where:{_and:[{productType:{slug:{_in:$typeSlugs}}},{root:{profileTags:{tag:{slug:{_eq:$tag}}}}},{_not:{productStatus:{slug:{_in:$dead}}}}]}}){_count rootId{_count_distinct}}}","variables":{"typeSlugs":["decentralised_exchange","dex_aggregator"],"tag":"solana","dead":["discontinued","support_ended"]}}
JSON

Keyword-based (quick check):

query ProductSaturation($q: String!) {
  productsAggregate(filter_input: { where: { name: { _contains: $q } } }) {
    _count
    rootId { _count_distinct }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query ProductSaturation($q:String!){productsAggregate(filter_input:{where:{name:{_contains:$q}}}){_count rootId{_count_distinct}}}","variables":{"q":"drift"}}
JSON

Advanced / Keyed Endpoints (If You Have Access)

The following is an example of an endpoint that requires an xApiKey GraphQL argument. Do not assume this works without explicit access.

query AlphaVybeRanking($xApiKey: String!) {
  alphaVybeRanking(xApiKey: $xApiKey, limit: 10) {
    date
    interval
    limit
    data {
      programId
      programName
      programRank
      score
      smartContract { address name }
    }
  }
}

curl -sS -X POST "$THEGRID_GRAPHQL_ENDPOINT" "${H[@]}" --data-binary @- <<'JSON' | jq '{data, errors}'
{"query":"query AlphaVybeRanking($xApiKey:String!){alphaVybeRanking(xApiKey:$xApiKey,limit:10){date interval limit data{programId programName programRank score smartContract{address name}}}}","variables":{"xApiKey":"REQUIRES_ACCESS_KEY"}}
JSON

Idea-Generation Workflow (Recommended)

1. Map topic to slugs: Use the Product Type Slug Taxonomy to identify 1-3 productType slugs for your domain. 2. Vertical Search: Run the Vertical Search recipe with your slugs + Solana scoping to get the highest-precision incumbent list. 3. Broad Keyword Search: Run the Broad Keyword Search for recall — catches products that don't fit standard categories. 4. Saturation check: Run the category-based aggregate to count total products and distinct roots. This grounds your "crowded vs. whitespace" assessment. 5. Expand top incumbents: Pick 3-5 top results and expand their root profiles (descriptions, tags, socials, product lists). 6. Map dependencies: For each incumbent product, map supportsProducts (what they depend on) and supportsProductsBySupportsProductId (what depends on them) to find missing primitives. 7. Asset mapping: Find key token(s) and where they are distributed/governed. 8. Tag-based discovery: Use profile tags to explore adjacent ecosystems or niche intersections (e.g., solana + defi).

Terms / Attribution

• The Grid docs: https://docs.thegrid.id
• Explorer reference implementation: https://github.com/The-Grid-Data/Explorer
• Respect The Grid licensing/terms. The Explorer repo notes that the Explorer code is MIT-licensed, but The Grid data service is separately licensed under The Grid's Web Services Terms unless you have a separate signed order.

Research Workflow — Deep Reference

This is the detailed reference for the 8-step research workflow. For a quick overview, see the main skill file.

Research Workflow

Use this workflow when conducting deep research on crypto/blockchain topics. It ensures comprehensive coverage across all data sources and produces actionable opportunity analyses.

When This Workflow Activates

This workflow runs ONLY when the user explicitly requests a deep analysis:

• "vet this idea", "deep dive", "full analysis", "validate this"
• "is [X] worth building?", "should I build [X]?"
• User accepts your offer: "Want me to do a full deep-dive on this?"

Do NOT run this workflow for simple questions, project lookups, archive searches, or hackathon comparisons. Answer those conversationally with targeted API calls.

Output Philosophy

This is not just a landscape report. It's an actionable opportunity analysis.

Your output should help a founder explore and refine an idea. That means:

1. Be specific, not vague. "Gap in payments" is useless. "SMEs wait 60-90 days for invoice payment, creating a $2.5T global liquidity gap" is actionable.

2. Ground claims in evidence. Every insight should trace to: hackathon project data, archive sources, or web search results. If you can't cite it, don't claim it.

3. Address the hard questions. Two-sided marketplace? Say so and explain the cold start problem. Regulatory risk? Name the jurisdictions. Don't hide friction.

4. Map the landscape for research and inspiration. Show founders what's already been built, who the key players are, and where the interesting angles lie. Competition is normal and healthy — most incumbents aren't unbeatable. Frame existing players as market validation and learning opportunities, not deterrents.

5. Connect to foundational concepts. The archives contain cypherpunk wisdom on escrow, bearer certificates, reputation systems, etc. Use them to validate or challenge ideas.

6. Research before deep-diving. Before claiming a gap exists, search for what existing players already offer. "Lots of hackathon projects building X" doesn't mean "X is unsolved" — it might mean the space has strong demand and existing traction worth studying. Use this research to help founders find their unique angle.

7. No execution chatter in user-facing output. Don't narrate your process ("Now let me search...", "I'll check the archives next..."). Perform verification internally; present findings directly.

8. Surface relevant context. "Tokamai (C2, funded) is building monitoring infrastructure with paying customers — study their approach for inspiration" is more useful than vague hand-waving. Founders benefit from knowing who else is in the space so they can learn from them and find their own differentiated angle.

Important Disclaimers (Include in Every Report)

Include these disclaimers in every deep-dive report:

1. Hackathon project context: "Most hackathon projects don't turn into successful startups. The projects surfaced here are useful for inspiration and seeing what's been tried before." 2. Project activity status: "Projects surfaced in this report may no longer be active. Verify current status before drawing conclusions about the competitive landscape."

Place these as a brief note near the top of the "Similar Projects" section.

Reusing Prior Results

If this deep dive follows a conversational exchange on the same topic, carry forward any results already obtained (project lists, archive citations, Grid data). In Step 2, skip calls that duplicate prior coverage — only run searches for dimensions not yet explored. In Step 5, mark checklist items as satisfied when prior evidence already covers them.

For archives specifically: if Step 2b already returned highly relevant documents (similarity > 0.40), skip the Step 7c search query and instead fetch the full text of the best Step 2b results using the /archives/:documentId endpoint with maxChars=8000. Only run a new Step 7c search if your Step 2b results were tangential to the deep-dive opportunity.

Step 1: Parse the Research Topic

Extract from the user's input:

• Core concept (1-2 sentences summarizing what to research)
• Target audience (builders, researchers, investors, etc.)
• Key dimensions (technical depth, historical context, market analysis)
• Domain context (if mentioned — e.g., "DeFi", "privacy", "infrastructure")

If the topic is broad, identify the most relevant angles to explore.

Step 2: Parallel Search [execute in parallel when possible]

Concurrency note: The API allows 2 in-flight requests, enforced server-side. Submit all Step 2 calls in a single response — your runtime serializes overflow automatically. If you get 429 RATE_LIMITED, honor the Retry-After header before retrying; for concurrency hits specifically, wait for in-flight requests to complete.

Context budget: After each sub-step, extract only the data you need going forward (top 3-5 results with names, slugs, scores; relevant tags; saturation counts). Do not carry raw API JSON into later steps — summarize inline and discard full payloads. If you need dropped details later, re-fetch rather than persisting large payloads.

Execute all Step 2 searches in a single response:

2a. Search Projects (minimum 2 queries required)

Run at least 2 `search/projects` calls with distinct formulations:

Query 1 — Semantic rewrite: Rephrase the topic in natural language, focusing on what the user is trying to accomplish.

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/projects" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<semantic rewrite of topic>",
    "limit": 10,
    "filters": {
      "winnersOnly": false,
      "acceleratorOnly": false
    }
  }'

Query 2 — Problem-space rewrite: Reframe around the underlying problem or user pain point rather than the solution category.

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/projects" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<problem-space rewrite of topic>",
    "limit": 10,
    "filters": {
      "winnersOnly": false,
      "acceleratorOnly": false
    }
  }'

Hackathon concentration check: If the top results from both queries are dominated by a single hackathon (> 70% from one), reformulate with a different angle and search again to ensure cross-hackathon coverage.

Dedup check: If multiple results share the same GitHub URL or team name (e.g., credencechain-1 and credencechain-2), treat them as one project with multiple submissions. Count competitors by distinct teams, not submission slugs.

Tag-filtered follow-up: Use the problemTags or solutionTags from your top 3 search results (not the global facets distribution) to pick follow-up filter tags. Note: facets returned by includeFacets: true reflect corpus-wide tag counts, not tags specific to your search results — they show landscape density but are misleading for targeted follow-ups. For filter-only follow-ups, omit query entirely (do not send ""):

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/projects" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "filters": {
      "problemTags": ["<top-problem-tag-from-facets>"],
      "winnersOnly": false
    }
  }'

Query 3 — Accelerator portfolio check (REQUIRED): After Queries 1-2 complete, run a third search targeting accelerator companies:

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/projects" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<same semantic rewrite as Query 1>",
    "limit": 10,
    "filters": { "acceleratorOnly": true }
  }'

Sequencing: Run Query 3 AFTER Queries 1-2 complete (2 concurrent max).

• If accelerator results directly match → carry to Step 6e as related builders to highlight.
• If accelerator results are adjacent (same vertical, different approach/segment) → note them as "Adjacent accelerator companies" in the report and explain the differentiation. These inform the opportunity landscape without triggering the Direct Competitor Alert.
• If no accelerator results match → note "No accelerator portfolio overlap found."

2b. Search Archives (Dual-Track Semantic Search)

Run two archive searches in parallel — one conceptual, one implementation-focused:

A) Conceptual query (timeless primitive):

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/archives" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<conceptual theme, 3-6 focused keywords>",
    "limit": 5,
    "maxChunksPerDoc": 1
  }'

B) Implementation query (modern ecosystem specifics):

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/archives" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<implementation-specific theme, 3-6 focused keywords>",
    "limit": 5,
    "maxChunksPerDoc": 1
  }'

Archive guardrails:

• Keep queries to 3-6 focused keywords (not 2-word fragments, not full sentences).
• If top results are all pre-2010 and the prompt is about modern implementation, re-query with ecosystem-specific terms (Solana, SPL, Anchor, Token-2022, etc.).
• Prefer 3-4 high-quality archive citations over padding to 5 with tangential references.

Note: Archive search auto-cascades through tiers (vector → chunk text → doc text) when a tier returns empty. If results are still empty after cascade, or are low-quality, try these query-refinement strategies (in order): 1. Synonyms: Replace domain-specific jargon with broader terms (e.g., "futarchy" → "prediction markets governance", "MEV" → "frontrunning extraction") 2. Broader concept: Step up one abstraction level (e.g., "compressed NFTs" → "state compression", "invoice factoring" → "trade finance") 3. Source filter: Try restricting to a high-signal source (e.g., "sources": ["solana_repo_issues"] for protocol-level topics, "sources": ["cryptography_mailing_list"] for privacy/crypto primitives) 4. Different angle: Reframe around the underlying primitive rather than the application (e.g., "zk attestation" instead of "privacy compliance")

2c. Fetch Top Project Details

For the top 2 most relevant projects from search results:

curl -s "$COLOSSEUM_COPILOT_API_BASE/projects/by-slug/<slug>" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

2d. Hackathon Analysis (Topic-Aware Routing)

Route the research topic to the most relevant hackathon(s) before calling /analyze:

If you make any "recent", "before/after", or "trend across hackathons" claim, verify chronology first via GET /filters hackathons[].startDate or a result's hackathon.startDate. Never infer order from names alone.

Run /analyze with all routed hackathons (multi-hackathon calls preferred for broader coverage):

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/analyze" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "cohort": { "hackathons": ["<routed-hackathon-1>", "<routed-hackathon-2>"] },
    "dimensions": ["tracks", "problemTags", "techStack"],
    "topK": 8,
    "samplePerBucket": 1
  }'

Use the tag distributions to identify which areas are crowded (high count) vs. underexplored (low count or absent). This directly informs angle selection in Step 3.

2e. Ecosystem Check (The Grid) [3-PHASE]

Query The Grid to identify established products in this space. Run all three phases — they serve different purposes.

Phase 1: Category Search (highest precision — start here)

Map your research topic to 1-3 productType slugs from the cheat sheet below, then query products filtered by those slugs with Solana ecosystem scoping. The triple-OR Solana filter covers deployments, support edges, and profile tags for maximum recall:

Shell escaping note: The --data-binary @- <<'QUERY' heredoc syntax works in standard bash. If your runtime has issues with heredocs, use inline JSON instead: --data-binary '{"query":"...","variables":{...}}' (escape inner quotes). Alternatively, write the JSON to a temp file and use --data-binary @/tmp/query.json.

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query VerticalSearch($typeSlugs:[String!]!,$chain:String!,$tag:String!,$dead:[String!]!,$limit:Int!){products(limit:$limit,where:{_and:[{productType:{slug:{_in:$typeSlugs}}},{_or:[{productDeployments:{smartContractDeployment:{deployedOnProduct:{name:{_eq:$chain}}}}},{supportsProducts:{supportsProduct:{name:{_eq:$chain}}}},{root:{profileTags:{tag:{slug:{_eq:$tag}}}}}]},{_not:{productStatus:{slug:{_in:$dead}}}}]}){id name productType{slug name}productStatus{slug}root{slug urlMain gridRank{score}}}}","variables":{"typeSlugs":["<slug1>","<slug2>"],"chain":"Solana Mainnet","tag":"solana","dead":["discontinued","support_ended"],"limit":25}}
QUERY

Topic → slug mapping guide:

Top 30 product type slugs by count: developer_tooling (599), wallet (331), decentralised_exchange (207), centralised_exchange (182), financial_services_platform (174), merchant_payment_gateway (159), on_off_ramp (145), l1 (144), payments_infrastructure_and_orchestration (136), game (131), decentralised_borrowing_and_lending (114), yield_aggregator (113), block_explorer (113), ai_agent (104), bridge (101), onchain_data_api (100), dex_aggregator (81), depin (80), ai_agent_platform (77), cross_chain_infrastructure (73), stablecoin_issuance (71), nft_marketplace (68), peer_to_peer_and_remittance (67), decentralised_identity (55), oracle (46), derivatives (46), embedded_wallet (46), rpc_provider (44), prediction_markets (28), ai_agent_framework (27). Total: 115 slugs — query productTypes for the full list.

Topic doesn't map to existing slugs? If no confident 1-3 slugs emerge from the mapping table: 1. Skip Phase 1 (category search) and run Phase 2 (keyword search) first 2. Extract recurring productType.slug values from keyword hits and pick up to 3 inferred slugs 3. Re-run Phase 1 + Phase 3 with inferred slugs if any emerge 4. If no stable slugs emerge, proceed with keyword-only evidence and note: "No reliable productType slug mapping exists for this topic — ecosystem maturity signal."

Phase 2: Keyword Recall (broad net — catches products that don't fit standard categories)

Search across product name, description, root slug, and entity names:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query BroadKeyword($q:String!,$dead:[String!]!,$limit:Int!){products(limit:$limit,where:{_and:[{_or:[{name:{_contains:$q}},{description:{_contains:$q}},{root:{slug:{_contains:$q}}},{root:{entities:{_or:[{name:{_contains:$q}},{tradeName:{_contains:$q}}]}}}]},{_not:{productStatus:{slug:{_in:$dead}}}}]}){id name description productType{slug name}productStatus{slug}root{slug urlMain}}}","variables":{"q":"<topic keyword>","dead":["discontinued","support_ended"],"limit":15}}
QUERY

Phase 3: Saturation Check (how crowded is this space?)

Run productsAggregate with the same category filter from Phase 1 to get total product count and distinct root count:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query Saturation($typeSlugs:[String!]!,$tag:String!,$dead:[String!]!){productsAggregate(filter_input:{where:{_and:[{productType:{slug:{_in:$typeSlugs}}},{root:{profileTags:{tag:{slug:{_eq:$tag}}}}},{_not:{productStatus:{slug:{_in:$dead}}}}]}}){_count rootId{_count_distinct}}}","variables":{"typeSlugs":["<same slugs as Phase 1>"],"tag":"solana","dead":["discontinued","support_ended"]}}
QUERY

After all phases: Merge results from Phase 1 and Phase 2. Rank by gridRank.score (if available) and productStatus. Note the top 5-10 key players — these become your landscape baseline for Step 6. Record the saturation numbers from Phase 3 (total products, distinct roots) — you will need them when identifying differentiation opportunities in Step 6c and writing your final report.

Step 3: Identify Research Angles

Based on projects, archives, and hackathon analysis, identify 2-3 distinct research angles worth exploring further.

If you ran `/analyze` in Step 2d, use the results to inform angle selection:

• High-count tags → saturated areas (potential red ocean); angle should explain why there's still room
• Low-count or absent tags → potential whitespace; angle should validate whether the gap is real
• Tag combinations (e.g., high defi + low privacy) → intersection opportunities

Format as JSON:

[
  {
    "angle": "Short name",
    "concept": "What makes this angle interesting - the key insight or gap",
    "query": "Web search query to explore current landscape"
  }
]

Each angle should:

• Surface a distinct perspective on the topic
• Connect to foundational concepts or emerging trends
• Be specific enough to validate via web search
• Reference hackathon data if available (e.g., "Only 4% of Breakout + Radar submissions addressed X")

Step 4: Landscape Analysis [execute in parallel when possible]

For EACH angle, do a web search in a single response (parallel tool calls).

For each result, summarize:

• Key players: Companies, protocols, and projects in this space
• Recent developments: Funding, launches, announcements (2024-2025)
• Research and standards: Academic papers, specifications, governance proposals
• Maturity level: Emerging | Growing | Established | Saturated

Suggested query patterns:

• "{concept}" crypto startup funding 2024
• "{concept}" production on Solana
• "{concept}" protocol standard specification

Step 5: Verification Checklist

Before synthesis, internally verify ALL of these are complete. This is a self-check — do not display checklist items or execution logs to the user:

• [ ] search/projects returned results (if empty, broaden query)
• [ ] search/archives returned results (if empty, try different conceptual framing)
• [ ] Web search called for EACH angle (not just one)
• [ ] At least one projects/by-slug call for detailed evidence

Coverage depth checks (REQUIRED):

• [ ] 2+ distinct project queries executed — confirm you ran at least two search/projects calls with meaningfully different formulations (semantic rewrite + problem-space rewrite). Two queries with minor word swaps do not count.
• [ ] One tag/filter follow-up query executed — confirm you used facet data from an initial search to run a filtered follow-up query (see Step 2a tag-filtered follow-up).
• [ ] Cross-hackathon coverage confirmed — results should span multiple hackathons. If you describe evolution across hackathons, verify chronology with startDate; if a single hackathon dominates (> 70%), either reformulate and search again, or explicitly document why single-hackathon coverage is intentional (e.g., the topic only appeared in one hackathon edition).
• [ ] Accelerator portfolio checked — Query 3 (acceleratorOnly) executed and outcome documented

If any are missing, execute the missing calls NOW before proceeding.

After completing initial synthesis (through "Opportunities & Gaps"), verify validation and deep dive:

Market Research (REQUIRED):

• [ ] Key players identified for top opportunity
• [ ] Web search completed for existing players' current features
• [ ] Landscape mapped and differentiation angle identified

Deep Dive Research (only after market research completes):

• [ ] Problem/TAM web search completed
• [ ] Revenue model web search completed
• [ ] Foundational archive search completed (with full document fetch if promising)
• [ ] Go-to-market case study search completed

Do not skip market research. Understanding the landscape helps founders find their unique angle.

Step 6: Market Landscape Research [CRITICAL - DO NOT SKIP]

Before deep-diving on any opportunity, research the existing landscape to understand what's been built and where differentiation opportunities exist.

6a. Identify Key Players

Who are the current players in this space? (e.g., Jupiter for DEX aggregation, Stripe for payments)

If you identified key players in Step 2e's Grid check, expand their root profiles now using the Root Profile query.

Finding the root slug: If a key player was identified via web search (not Grid), search for their Grid presence using Phase 2's keyword query with the company name. If no Grid entry exists, note "Not indexed on the Grid" and rely on web search evidence for the landscape analysis.

Expand root profiles using:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query RootProfile($slug:String!){roots(limit:1,where:{slug:{_eq:$slug}}){id slug urlMain gridRank{score}profileInfos{tagLine descriptionShort descriptionLong}urls{url urlType{slug name}}socials{name socialType{slug name}urls{url}}products(limit:10,order_by:{name:Asc}){id name productType{slug name}productStatus{slug name}}profileTags(limit:10){tag{slug name}}}}","variables":{"slug":"<incumbent-root-slug>"}}
QUERY

Pull the full product list, tags, socials, and URLs. This gives you concrete data about what they actually offer — don't rely on assumptions.

6b. Research Existing Players' Offerings

Use web search:

• Query: <key player> <proposed area> features how it works 2025

Also expand the player's product graph to map dependencies and reverse dependencies:

curl -s -X POST "https://beta.node.thegrid.id/graphql" \
  -H "content-type: application/json" \
  --data-binary @- <<'QUERY'
{"query":"query ProductSupportGraph($productId:String!){productsById(id:$productId){id name root{slug urlMain}supportsProducts(limit:25){supportsProduct{id name root{slug urlMain}}}supportsProductsBySupportsProductId(limit:25){product{id name root{slug urlMain}}}}}","variables":{"productId":"<incumbent-product-id>"}}
QUERY

supportsProducts = what they depend on. supportsProductsBySupportsProductId = what depends on them. Gaps in this graph may reveal integration opportunities.

Ask explicitly:

• Do existing players already offer this?
• When did they ship it? (Recent = there's clear market demand)
• How sophisticated is their solution? Where are the gaps or underserved segments?

6c. Identify Differentiation Opportunities

Classify the opportunity landscape into one of three categories.

Use the saturation count from Step 2e Phase 3 to ground your classification. A category with 3 products and 3 distinct roots has a different competitive dynamic than one with 200 products across 150 roots.

1. Open space — Based on the available data, no existing player appears to have meaningfully addressed this problem. Proceed to Step 7. 2. Differentiation opportunity — Existing players have solutions, but there are specific angles a new entrant could pursue:

• Segment opportunity: They don't serve a specific user segment well (e.g., "Jupiter doesn't serve institutional traders who need compliance features")
• UX opportunity: The feature exists but is buried, confusing, or requires technical knowledge (e.g., "Solana staking exists but requires CLI knowledge")
• Geographic opportunity: Not available or poorly adapted for specific markets (e.g., "no fiat onramps for Southeast Asian currencies")
• Pricing opportunity: Existing players charge too much for a segment that needs a cheaper alternative
• Integration opportunity: Works in isolation but doesn't compose well with the rest of the ecosystem

3. Well-covered space — Multiple established players serve this need effectively. Help the founder understand the landscape and suggest adjacent or complementary angles they could explore instead.

Help founders find their angle. Even in well-covered spaces, there may be underserved segments, novel approaches, or complementary products worth building. Frame this as market intelligence, not discouragement.

6d. Document Your Research

In the final report, include a section: "Market Landscape" that shows:

• What existing players currently offer (useful for research and inspiration)
• Where differentiation opportunities exist (with evidence)
• Or why you explored a different angle
• Grid evidence (required): key player product IDs, root slugs, product types, and saturation counts from Step 2e Phase 3. If Grid data contradicts your web search findings, flag the discrepancy explicitly.

6e. Related Builder Highlight

If any project from Step 2a — including the accelerator check — has high semantic overlap with the user's idea (same problem, same target user, similar approach):

Surface this prominently in your report's Market Landscape section. Format:

Related Builder: [Name] (slug, [Hackathon/Batch]) is working on [overlap].

Status: [active/funded/shipped/pivoted]. Study their approach for inspiration.

To differentiate, consider: [specific angle — segment, geography, UX, pricing, or integration].

Evidence requirements for highlighting:

• Matching problem space (not just category)
• Matching target user segment
• Similar technical approach or distribution strategy

Help the founder understand what's been tried and suggest concrete differentiation angles (segment, geography, UX, pricing, or integration).

Grounding rule: When noting overlap with existing builders, be specific about what they've built and where the differences lie. Vague claims like "there's room for both" aren't helpful — instead, identify the specific underserved segment or novel angle the founder could pursue.

Step 7: Deep Opportunity Research [AFTER MARKET RESEARCH]

Only proceed here after Step 6's market landscape research is complete.

7a. Problem & User Research

Use web search: <opportunity> market size TAM problem friction pain point

Look for: specific friction points, user personas, market sizing data, industry reports.

7b. Revenue Model Research

Use web search: <opportunity> business model revenue pricing startup funding

Look for: how comparable companies charge, unit economics, funding rounds (implies revenue potential).

7c. Foundational Grounding (Archives)

curl -s -X POST "$COLOSSEUM_COPILOT_API_BASE/search/archives" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<underlying primitive, 3-6 focused keywords>",
    "limit": 3,
    "maxChunksPerDoc": 2
  }'

Deep-dive pass: Use maxChunksPerDoc: 2 here (vs. 1 in exploratory Step 2b) to get richer context from documents you already know are relevant.

For promising archive results, fetch full text:

curl -s "$COLOSSEUM_COPILOT_API_BASE/archives/<documentId>?offset=0&maxChars=8000" \
  -H "Authorization: Bearer $COLOSSEUM_COPILOT_PAT"

Look for: foundational concepts from cypherpunk/crypto literature that validate or inform the opportunity.

7d. Go-to-Market Case Studies

Use web search: <similar company or space> cold start bootstrap marketplace strategy

Look for: how comparable two-sided markets bootstrapped, anchor customer strategies, vertical focus approaches.

Step 8: Synthesize Report

Output-budget guardrails (REQUIRED):

• Complete all 7 deep-dive subsections before any supplementary content.
• Keep pre-deep-dive sections concise so the deep dive can finish.
• If approaching output limits, prioritize in this order:

1. Risk Assessment 2. Founder-Market Fit 3. Why Crypto/Solana? 4. Further Reading (appendix, optional)

• Do not add source dumps or supplementary appendices before deep-dive completion.

Compact mode (when approaching output limits):

• "Why Crypto/Solana?" can be reduced to 1-2 bullets when the crypto angle is obvious.
• "Founder-Market Fit" can be omitted when the ideal founder profile is self-evident.
• Merge "Key Insights" + "Opportunities & Gaps" into a single "Insights & Gaps" section.
• Cap "Current Landscape" to the top 2 angles (drop the weakest).
• Keep all other Deep Dive subsections required.

Generate the final report with these EXACT sections in this order:

---

Similar Projects (5-8 bullets)

Note: These are hackathon submissions — demos and prototypes, not production products. Many may no longer be active. They're included as inspiration and to show what's been tried before, not as a competitive landscape.

Format: [Project Name] (slug) - one-line description

• Include the slug for reference
• Note prize placement if applicable
• Highlight notable implementations or approaches

Archive Insights (3-5 bullets)

Format: [Source] - concept and relevance

• Reference cypherpunk/crypto archive sources
• Connect to foundational ideas and their evolution

Current Landscape

One subsection per research angle:

[Angle Name]

• Key players: Companies, protocols, projects
• Recent developments: Funding, launches (2024-2025)
• Research & standards: Papers, specifications
• Maturity: Emerging | Growing | Established | Saturated

Key Insights

• Patterns: Recurring themes across projects and research
• Gaps: Underexplored areas with evidence
• Trends: Direction the space is moving

Opportunities & Gaps

• Underexplored areas: Where few projects have been built
• Emerging niches: Early-stage but promising
• Established spaces: Well-covered areas where differentiation requires a strong angle

---

Deep Dive: Top Opportunity

Select the single highest-potential opportunity from the gaps identified above. Analyze it across these dimensions:

Market Landscape (REQUIRED)

• Who are the key players? Name existing players and their approaches
• What do they currently offer? Specific features that address this problem space
• Landscape classification: One of:
• Open space: Based on the available data, no existing player appears to have meaningfully addressed this. [Evidence]
• Differentiation opportunity — Segment: They don't serve [specific user segment] well because [reason]
• Differentiation opportunity — UX: Feature exists but [specific UX problem]
• Differentiation opportunity — Geographic: Not available/adapted for [specific market]
• Differentiation opportunity — Pricing: Too expensive for [specific segment]
• Differentiation opportunity — Integration: Doesn't compose with [specific ecosystem need]
• Well-covered space: Multiple established players serve this need. Consider adjacent angles: [suggestions]
• Evidence: Link to or cite the source that informed this analysis

Use this landscape research to help the founder find their unique angle and learn from what's been built before.

The Problem

• What is the concrete friction? Not "gap in market" but the specific pain point (e.g., "businesses wait 60-90 days for invoice payment, can't make payroll")
• Who experiences this pain? Specific user persona with context (e.g., "textile manufacturer in Vietnam shipping to H&M")
• How do they solve it today? Current workarounds and why they're inadequate
• What's the quantified impact? Dollar amounts, time costs, market size with sources

Revenue Model

• How does this make money? Specific fee structure (e.g., "0.5% transaction fee on invoice purchases")
• Unit economics: Revenue per transaction/user, margins
• TAM calculation: Show the math (e.g., "$17T trade finance market x 0.1% capture x 2% fee = $34M")
• Comparable business models: Who else makes money this way? (traditional or crypto)

Go-to-Market Friction

• Is this a two-sided marketplace? If yes, identify both sides clearly
• Cold start problem: Which side do you need first? Why would they show up without the other?
• Bootstrap strategies:
• Can you be one side yourself initially? (e.g., be the first buyer/seller)
• Is there an anchor customer strategy? (one large customer whose network follows)
• Can you start in a niche vertical?
• Network effects: Once bootstrapped, does it get easier or stay hard?

Founder-Market Fit

• Ideal founder background: What specific experience solves the cold start? (e.g., "ex-trade finance banker with anchor buyer relationships")
• What they bring: Relationships, expertise, or capital that shortcuts the hard parts
• Red flags: Who should NOT build this? (e.g., "pure crypto native with no lending experience")
• Team composition: If not solo, what complementary roles are needed?

Why Crypto/Solana?

• What does blockchain specifically enable? Not "decentralization" but concrete capabilities (e.g., "global stablecoin liquidity pools, fractional NFT ownership, instant settlement")
• Could this be built without crypto? If yes, what's the crypto advantage?
• Why Solana specifically? Speed, cost, ecosystem, or other factors

Risk Assessment

• Technical risk: Is the core technology proven?
• Regulatory risk: What jurisdictions matter? What's the compliance path?
• Market risk: Is this a "vitamin" (nice to have) or "painkiller" (must have)?
• Execution risk: What's the hardest part to get right?

---

Appendix (Optional): Further Reading

3-5 specific follow-ups: projects to study, communities to join, papers to read, queries to run.

---

Key synthesis rules:

• Use bullet points, not tables
• Keep descriptions concise (1-2 sentences max)
• Include project slugs for reference
• Evidence-based observations, not speculation
• Prioritize depth and accuracy over breadth
• Treat Further Reading as optional; omit it if needed to complete deep-dive sections
• Inline citations only. Cite sources inline in bullets (project slugs, archive titles,

URLs). Do NOT add a separate "Sources" or "References" section at the end. The Appendix (Further Reading) is the only place for additional references.

---