CoW Protocol Integration Documentation

[Sov]

CoW Protocol’s current documentation creates measurable friction for integrators. BD has reported that even large partners (Binance-tier) struggle with basic order creation. The search functionality returns poor results. Parameter descriptions are written from an internal engineering perspective rather than from an integrator’s.

Recent examples illustrate the gap. A team that has already integrated limit orders reached out to ask how to set token approval via the ABI for a gasless swap. Another partner couldn’t determine that the buy amount field requires slippage to be packed in. These aren’t conceptual misunderstandings. They lack the parameter-level clarity that the existing documentation lacks.

This adds unnecessary steps to what should be a straightforward integration path. Every extra click or context switch is an opportunity for a partner to deprioritize the integration or reach out to BD for help that documentation should provide.

Reference Models

The council identified DFlow (Solana) as the north star. After reviewing their documentation alongside Jupiter and 0x, clear patterns emerge.

• DFlow organizes endpoints by use case rather than internal architecture. Each endpoint page includes a description, a parameter table with types and constraints, a response schema, and cURL examples. An “Ask AI” button appears on every page. Their quickstart guides help integrators through end-to-end workflows.

• Jupiter takes a two-tier approach with Ultra (simple) and Swap API (advanced), providing clear guidance on when to use which. Code examples in TypeScript appear directly on reference pages alongside migration guides.

• 0x provides a cheat sheet for quick contract and endpoint reference, decision trees for choosing between integration approaches, and human-readable error documentation. Their quickstart helps developers go from zero to their first successful call.

The common thread across all three: endpoint reference pages with parameter tables, code samples in multiple languages, interactive playground functionality, a quickstart that delivers results in under 10 minutes, and an error code reference with troubleshooting steps.

Approach Options

This RFC invites proposals across a spectrum of approaches. Applicants should indicate which track they propose to join.

Track A: Systematic/AI-Based

Proposals that deploy trained RAG systems, documentation generators, or other programmatic approaches that pull from source code and existing documentation. These solutions sit as a meta-layer that improves as the underlying documentation improves.

The council will evaluate Track A proposals based on demonstrated framework or methodology from previous deployments, how training data is sourced and maintained over time, and operational cost structure, including API access and hosting. Applicants should provide sample queries and outputs from similar projects to demonstrate accuracy. The council will also consider the review burden: what does the core team need to verify before each release?

Track B: Targeted Long-Form

Proposals for manual documentation of specific high-friction areas. These require depth of subject-matter expertise and will require core team availability for interviews and technical reviews.

The council will evaluate Track B proposals based on portfolio quality, with a focus on similar API or integration documentation. Applicants should propose specific sections rather than a vague, full-overhaul pitch, estimate the core team hours needed for interviews and reviews, and describe their process for validating technical accuracy before delivery.

The council may fund multiple proposals across both tracks if responses warrant it.

Target Scope

The primary objective is to make the integration setup clear for developers with limited context on CoW Protocol internals. This is not about conceptual explanations (which exist) but parameter-level precision.

Priority areas based on BD feedback:

• Order creation: which fields require slippage, and how amounts should be formatted
• Approval setup: ABI-level guidance for relay approval patterns
• Error responses: what each error means and how to resolve it
• Endpoint selection: when to use fast vs optimal quoting

Phase 1 deliverables depend on the approach track. Track A should deliver a deployed system with sample queries demonstrating accuracy in priority areas. Track B should deliver restructured reference pages for the Order Book API, including parameter tables, type constraints, and plain-language descriptions. Both tracks should deliver a quickstart that gets an integrator to a successful first order in under 10 minutes, with correct amount calculation covering fees, slippage, and quote handling.

Out of scope: solver documentation, CoW AMM docs, MEV Blocker docs, platform migration, and conceptual guides for end users.

Coordination Requirements

Before finalizing any award, the council needs to confirm the scope boundaries between internal roadmap work and grant-funded work, the availability of technical reviewers for milestone reviews, and the core team’s bandwidth for applicant interviews (Track B in particular).

Applicants must specify:

• Estimated hours of core team time required
• Number and purpose of sync calls needed
• What existing documentation or source code access is required
• How will technical accuracy be verified without a heavy core team review

The Q1 roadmap includes partner usability improvements. Proposals should account for potential overlap and describe how they would coordinate rather than duplicate effort. The information architecture work should align with the existing product separation proposal (PR #551). The core team should address Swagger/OpenAPI sync as a prerequisite to ensure documentation accuracy remains maintainable.

Applicant Profile

Track A applicants should have prior experience with documentation generation or RAG-based systems and a demonstrated record of output quality. They need an understanding of operational costs and maintenance requirements, and familiarity with parsing OpenAPI/Swagger specifications programmatically.

Track B applicants should have a portfolio that includes API documentation for DeFi or trading systems and experience interviewing subject-matter experts to extract technical details. Availability for 3-5 sync calls with the core team during execution is required, along with familiarity with Docusaurus or similar static site generators.

Both tracks benefit from a Web3/DeFi background, understanding of EVM transactions and approval patterns, and prior work with intent-based trading, batch auctions, or aggregator protocols.

Submission Guidance

Proposals should include:

• Which track (A, B, or hybrid) proposing under
• Specific sections or capabilities you would deliver
• Estimated budget range and timeline
• Estimated core team time required
• For Track A: example outputs from similar deployments
• For Track B: portfolio links to comparable documentation work

The council may select multiple proposals if complementary approaches emerge.

[mig]

What I built - https://cow-docs-ai.vercel.app/

A documentation assistant for CoW Protocol that gives integrators precise, parameter-level answers about the protocol’s API.

I ingested the public CoW GitHub docs and the Orderbook OpenAPI spec, resolved all schema references ($ref, allOf, enums, constraints), and indexed endpoints, schemas, and errors into a vector database. Retrieval happens at the schema level; not paragraph-level keyword matching.

The MVP is live and nearly fully functional. This grant covers final benchmarking, test expansion, and frontend polish before production handover.

---

How it works

RAG architecture. Postgres + pgvector (hosted on Neon) for vector storage, text-embedding-3-small for embeddings, configurable LLM layer (Claude 3.5 Sonnett, with Haiku and GPT-4o-mini as cost-optimized alternatives).

Ingestion pulls from public GitHub repos:

• Markdown docs → semantically chunked by section → stored as docs chunks

• OpenAPI spec → parsed, $ref resolved, allOf merged, enums/constraints extracted → stored as api-endpoint, api-schema, and api-error chunks

Each schema chunk preserves required/optional fields, types, formats, enum values, constraints, and descriptions.

Sync runs via cron. It monitors the repos, detects changes to markdown or the OpenAPI spec, re-indexes modified content, and removes deleted content. No manual intervention, no private access; everything comes from public GitHub.

---

What it can already do

• Field-level order creation guidance

• Slippage packing clarification

• Approval setup explanations

• Human-readable error troubleshooting

• Endpoint discovery and comparison

• cURL and TypeScript example generation

• Evaluation framework with scoring

• Admin dashboard for monitoring

Core functionality is stable.

---

What’s left

1. Model benchmarking: Compare Sonnet, Haiku, and GPT-4o-mini on parameter accuracy, hallucination rate, latency, and cost per query. Explore hybrid routing by complexity.

2. Test expansion: Scale the evaluation suite to 50+ golden questions covering slippage/amount formatting edge cases, approval flows, and error enum validation. Responses scored on keyword coverage, fact coverage, and hallucination detection. Regression tests run before any model or ingestion update.

3. Frontend refinement: Improve parameter table rendering, citation visibility, code formatting/copy UX, quick prompts for common flows, and admin evaluation views. Polish, not rebuilding.

---

Coordination

Minimal. Optional 45–60 min intro call, everything else async (shared doc, telegram). Estimated core team time needed from CoW: 4 hours total(testing).

Accuracy is enforced programmatically: direct OpenAPI parsing as source of truth, structured chunking, golden-question evaluation, and regression testing. The core team validates priority edge cases once; the test suite handles consistency from there.

---

Handover

Full repository transfer on completion: source code, ingestion scripts, database schema, evaluation framework, cron sync setup, and model configuration. The CoW team gets complete control over hosting, vector store, model provider, API keys, and deployment. Fully self-hostable.

---

About me

I’m Mig. I run DevRel and product extensions at Routescan. I previously managed the creation of an AI agent for on-chain analysis integrated across Routescan’s docs and API; same approach: structured ingestion from source-of-truth specs, vector-backed retrieval, configurable model layer, evaluation-driven validation.

---

Deliverables

1. Production-ready assistant

2. Model benchmarking report

3. 50+ golden-question evaluation dataset

4. Refined frontend

5. Documented accuracy metrics

6. Full repository transfer

Grant Request: $7,500: The core system is already built. This funds final benchmarking, testing, polish, and production hardening.

tg: @mig992

[Daniel_Woof]

Grant Application: CoW Protocol Integration Documentation

Woof is a high-agency Web3 development firm that builds the infrastructure DeFi actually runs on - migrators, staking systems, treasury tooling, and payment rails like Streamer. As the core development team for Compound Finance, we maintain docs.compound.finance and shipped the treasury dashboard that turns protocol-level accounting into readable analytics. We’ve also delivered to production systems for Silo, Benqi, EtherFi, and others across ecosystems such as Avalanche and Optimism.

Woof integrates DeFi protocols daily - and we know firsthand what incomplete parameter docs feel like, and we build documentation the way integrators actually need it.

The Problem

The developers spending hours trying to figure out why an order wasn’t going through, only to discover that buyAmount needed slippage packed in manually.

The current CoW documentation has the information, but it’s structured around the system’s internal logic, not around what an integrator needs to do. Three things are missing:

1. Parameter tables with real constraints and gotchas (e.g., “buyAmount includes slippage - you have to pack it in yourself”)

2. Quickstart guides that get you from zero to a working order in under 10 minutes

3. An error reference that explains why something failed, not just that it failed

We’re proposing a hybrid approach. Deliverables are split into Required (directly solves the RFC’s problems) and Recommended (additional value). The council can fund just the required portion or the full scope.

1. What’s definitely needed: Full Content Overhaul (Track B)

This is the foundation. No AI will help without it. We’re rewriting the docs from the perspective of “What do I need to do?" rather than “How does this work internally?” Here’s what you get:

Deliverable 1: New Order Book API Reference

Full restructure organized by use case, not by internal architecture. Parameter tables with real constraints, response schemas, and working code examples in TypeScript, Python, and cURL. We’ll document everything developers typically stumble on - the pitfalls we wish someone had told us about earlier.

Section	What gets documented
Order Creation	buyAmount must include slippage (the exact issue from the RFC). Wei formatting. validTo semantics. appData hash calculation.
Approvals	GPv2VaultRelayer addresses per chain. Gasless approval flow - the exact question from the RFC.
Quoting	Fast vs optimal - when to use which. Fee structure. Timing between quote and order creation.
Order Lifecycle	Statuses, cancellation (on-chain vs off-chain), expiry, replacements.
Rate Limits	Per-endpoint limits - important for bots and aggregator backends.

Deliverable 2: Quickstart Guides

Three paths to your first order in under 10 minutes:

1. Limit Order (TypeScript): approve → quote → sign → submit → check status
2. Gasless Swap (Python): full relay approval flow
3. Raw API (cURL): no SDK, just HTTP, works with any language

All three ship with a GitHub repo configured for Sepolia and CI that breaks when the API changes. No more silently outdated examples.

Deliverable 3: Error Reference (Human-readable)

We classify every error by integration stage (quoting, creation, signing, execution). For example, if you get InsufficientBalance, we’ll write straight up: “Most likely the issue is your allowance to the VaultRelayer, not your balance. Here’s how to check.”

2. What we recommend: AI Search Layer (Track A)

Once the content is ready, we propose adding smart search - a Docusaurus plugin.

Why this isn’t a regular chatbot:

• It knows OpenAPI: Parameter answers come directly from your openapi.yml, not from the LLM’s imagination.

• Safety-first: We know that hallucinations in DeFi mean risk of lost funds. So contract addresses are hardcoded in the config, and code is generated only from verified templates. It says “I don’t know” if it can’t back up an answer.

• Feedback loop: You’ll get a weekly report on what developers ask most often, tracking unanswered queries, and where the docs still have gaps and what’s missing.

Budget & Timeline

Milestone	Priority	Deliverables	Weeks	Payment
M1	Required	API Reference + Error Guide + Rate Limits	3	$10,800
M2	Required	3 Quickstarts + GitHub repo with CI	2	$7,200
M3	Recommended	AI Assistant + Docusaurus plugin + Gap Reports	2	$9,000
M4	Required	Core team review, PR merging, handoff, demo	1	$3,000

Required only (M1+M2+M4): $21,000 - gets the docs fixed.
Full scope (all milestones): $30,000 - adds AI search on top.

Coordination

Core team time: hours total across the engagement.

Activity	Hours	When
Kickoff: scope alignment, access, PR #551 alignment	1.5	Week 1
Technical review: parameter accuracy	4-6	Weeks 2-3
Quickstart validation	2-3	Week 4
AI answer quality review (Optional, if M3 funded)	2-3	Week 6
Final review and handoff	2	Week 8

Sync calls: 4-5 total (kickoff + one per milestone). Everything else is async - shared doc or Telegram.

How we maintain accuracy without heavy core team involvement: We cross-reference all content against the OpenAPI spec and Rust source code first. All code examples are tested on Sepolia before submission. The core team only reviews the delta - what we wrote, not what we sourced from the spec. We flag any places where the spec doesn’t match actual API behavior, contributing to the Swagger sync effort rather than blocking on it.

Handover

Documentation: Merged PRs in cowprotocol/docs. Standard markdown. CI on quickstarts automatically catches breakage.

AI (if M3 is funded): MIT license, open-source. Docker Compose for self-hosting. LLM-agnostic. Needs about 1-2 hrs/month from your side for major API updates.

TG contact for questions & feedback: @daniel1woof

[manu]

Hi CoW community,

At BootNode, we’ve been actively working on assessments and solutions to address documentation gaps and the friction our partners face when integrating their protocols. After reviewing the RFC, we’d like to share our thoughts on how to address these challenges.

Our goal isn’t just to “fix docs”, but to make the protocol easy to learn, integrate, deploy, test, and operate. Less friction → faster onboarding → more integrators. To keep the experience of “Time-to-first-success” under minutes and not hours. In addition to the North Star and other projects, we’ve benchmarked direct competitors with great docs.

1. Clarifications & Scope

To make sure we’re aligned with CoW’s immediate needs, we’d appreciate clarification on a few points before submitting any proposal:

Order Types:
CoW already supports everything from Market and Limit orders to CoW Hooks and Milkman. Should the initial effort cover the full suite, or should we prioritize a “Core Integration” subset (Market / Limit / TWAP)? How does the integration and utilization distribution look like (eg: 80% integrations are Marker Orders)

Approval Flow:
Are the current pain points primarily related to Permit2 vs. traditional approvals, or are there additional complexities in the gasless flow that should be addressed?

Error Mapping:
Rather than relying solely on generic HTTP codes, do you have a list of common “silent” failures or recurring partner questions that we should prioritize for clearer semantic documentation, besides the ones already shared by BD in the RFC?

Integration Issues:
Do you have tickets/issues you could share publicly regarding integrators’ struggles?

PR Reference:
The RFC references the “PR #551”, but we haven’t been able to locate it. Could you share the direct link so we have full context?

Other:
Would you be interested in adding readers’ feedback mechanisms (e.g., “Did you find what you need? Contact us.”)?

2. Proposed Execution Plan (Track B: Content & Integration)

M1 - Docusaurus Infrastructure Fix:
Address the broken indexing and search functionality. The current site appears to use an outdated version, like 3 years old; we would upgrade and reconfigure it to ensure content is properly discoverable.

M2 - The “Friction Test”:
DevEx Assessment: map the end-to-end developer journey and identify drop-offs and bottlenecks, focusing on order flow. By documenting every issue encountered while building a real-world order flow (e.g., slippage packing, quote selection).

M3 - API Semantic Enrichment:
Enhance the OpenAPI specification by adding clearer endpoint descriptions, distinguishing between optional and required parameters (e.g., using full vs. fast quotes), and documenting error responses in a structured, meaningful way.

M4 - CI-Driven Documentation:
Implement a CI check that consumes the production API. If an API change breaks the integration test, it would trigger a documentation review requirement to ensure the docs remain aligned with the codebase. AI can be used to (suggest) autocomplete for missing/outdated documentation updates.

M5 - Comprehensive Technical Guide:
Develop a step-by-step integration guide focused on the order creation use case. These would serve as the primary entry point for new partners, shifting from conceptual-only documentation to a hands-on tutorial that just works.

M6 - AI-Ready Assets (llms.txt):
Implement an automated pipeline to generate and host ../llms.txt, and ../llms-full.txt. Using tools like Crawl4AI, we can ensure AI agents have access to a condensed, high-signal version of the technical documentation.

3. Structural Strategy (Track A: Tooling & Framework)

Track A focuses on the tooling and can be developed in parallel. The emphasis would be:

1. Framework Evaluation:
   Provide a comparative analysis of modern documentation platforms (e.g., algolia, kapa, mintifly -used by DFlow-, among others) with a focus on search quality and AI readiness.

2. Context for Agents:
   Define best practices for implementing MCP (Model Context Protocol) to enable AI agents to navigate CoW’s documentation with greater precision. Custom skills will also be evaluated.

Why this approach?

By separating Content (Track B) from Framework (Track A), the protocol can move forward without creating bottlenecks. Different teams can work independently on each track while coordinating to evaluate how the tools proposed in Track A perform when combined with the high-quality content produced in Track B. This delivers immediate value for integrators and prepares the land for future AI tooling.

Closing

Focusing on Track B: Content & Integration, we would greatly value your opinion on the proposed plan and confirmation that it aligns with your expected direction. If you could clarify the questions raised in Section 1, we would be in a better position to generate a proposal.

[CoBuilders.xyz]

Grant Application: CoW Protocol Integration Documentation

Problem Statement

A developer builds an order submission flow. The request compiles. Parameters match the API reference. The order fails silently. A few hours later, the answer appears in the source code: buyAmount requires slippage to be packed manually.

Situations like this are common during a first integration. Developers often discover that some important behaviors, such as amount semantics, approval flows, or certain error responses, are clearer in the codebase than in the documentation.

Improving how these details are surfaced in the documentation could make the integration experience much smoother, allowing developers to build confidently without inspecting the source.

---

1. Why CoBuilders

CoBuilders is a technical research and development team that works with blockchain protocols on infrastructure, integrations, and developer tooling.

Our work focuses on the layer where developers actually interact with protocols: APIs, relayers, signing flows, and integration tooling. This perspective strongly influences how we approach documentation: not as external writers, but as builders who have faced the same integration challenges.

Our team has collaborated with organizations such as OpenZeppelin, Arbitrum, Worldcoin, and ZetaChain, delivering work that spans protocol research, developer infrastructure, and technical documentation.

Within the CoW ecosystem, we have already completed a grant project integrating Otterscan into the CoW Protocol Playground, improving transaction inspection and debugging for local development environments. The project progressed through multiple milestones and was delivered through public pull requests and documentation updates.

• December 5, 2025: grant approval by the CoW grants committee.

• February 28, 2026: milestone 3 completion posted.

• Source: CoW Forum grant thread

Additional technical documentation delivered:

Project	Repository	Live Docs
Hardhat Arbitrum Stylus	GitHub	Docs
Stylus CM Deploy	GitHub	Docs

Because of this background, we approach documentation from a practical integration perspective: identifying where developers actually get blocked and designing documentation that directly resolves those friction points.

---

2. What We Deliver

To address both immediate integration friction and long-term documentation maintainability, we propose a hybrid approach composed of two complementary tracks.

Track B: Targeted Long-Form

- Documentation Overhaul

Rewrite of every high-friction area identified in the RFC. All code examples are in TypeScript, Python, and cURL.

Area	What Changes
Order creation	Amount semantics, slippage packing, and fee handling, validTo semantics, appData hash. Field-level precision with working examples
Approval setup	GPv2VaultRelayer addresses per chain, gasless approval flow, ABI-level relay patterns
Quote selection	Fast vs optimal: when to use each, response differences, latency tradeoffs, timing between quote and order creation
Error reference	Structured by integration stage: quoting → signing → submission → settlement. Root cause + concrete fix for each
Rate limits & quotas	Per-endpoint limits, backoff strategy, quota headers, critical for bots and aggregator backends

To better identify real integration friction, we will also consult active integrators and developers building on CoW Protocol. These conversations help surface common onboarding blockers and ensure the documentation overhaul focuses on the issues developers actually encounter during integration.

- Three Quickstart Paths (< 10 minutes each)

Each targets a different integration pattern and language:

Path	Language	Use Case
Swap Order	TypeScript + Python	Frontend/dApp, most common integration entry point
Limit Order	TypeScript + Python	Backend bots, automation, algorithmic trading
Raw API	cURL	Quick exploration, language-agnostic validation

Each path goes from zero to a confirmed order on staging. Every quickstart is backed by an executable artifact that CI validates on every push.

- Full-Section Validation + Cross-Repo CI

Every authored section ships with:

1. A test-case manifest (YAML).

2. Executable code artifacts, the same snippets shown in the docs.

3. Deterministic pass/fail checks.

4. Evidence logs for reviewer verification.

Every authored documentation section is backed by executable code artifacts and a test manifest. When documentation or snippets change, CI runs these artifacts to verify they still match the expected API behavior.

To prevent documentation from drifting as the protocol evolves, the system also performs cross-repository drift detection. When a relevant cow-services repository merges into it main, it triggers a repository_dispatch event to the documentation repository. This automatically re-runs the artifact validation pipeline against the live API contract.

If an API change breaks a documented claim, the pipeline flags the mismatch and surfaces a visible warning so maintainers can update the documentation before integrators encounter stale information.

This goes beyond typical CI checks on quickstarts: it introduces contract-level validation between implementation and documentation across repositories.

Implementation details, including CI wiring, job topology, and notification channels, will be finalized with CoW maintainers to align with the existing repository governance.

---

Track A: Systematic/AI-Based

- MCP Assistant

An AI assistant exposed via the Model Context Protocol (MCP) that helps developers interact with protocol documentation and API specifications.

Rather than acting as a traditional chatbot, the assistant helps integrators navigate documentation and generate integration artifacts, such as request payloads, parameter explanations, and example snippets.

The final shape of the assistant will be defined collaboratively with the CoW core team. Two architectural approaches are possible.

Possible Approaches

1. Documentation RAG

One approach is to build a retrieval-augmented system that indexes the protocol documentation and OpenAPI specifications.

In this model:

• Documentation and specs are indexed and kept in sync with public sources.

• The LLM retrieves relevant documentation fragments and generates answers based on them.

• The assistant behaves similarly to an AI documentation reader that explains API behavior and integration patterns.

This approach prioritizes flexibility and natural documentation exploration.

2. Schema-driven MCP tools

Another approach is to expose deterministic tools derived from the OpenAPI specification through the MCP server.

In this model:

• Tools are generated directly from OpenAPI operations.

• The LLM interprets the user’s request and calls the appropriate tool.

• The tool produces structured outputs such as request payloads, parameter tables, or example code.

This reduces the risk of hallucinations because the LLM does not need to infer API schemas from documentation; the schema is generated directly from the spec and resolved by the tool.

These two approaches are not mutually exclusive, and the final implementation may combine both, for example:

• RAG for documentation discovery and conceptual questions

• deterministic tools for schema generation and request construction

The architecture will be finalized together with the CoW team once the integration requirements and preferred developer workflow are validated.

- Access Points

The assistant can be accessed from multiple environments:

• Documentation site, via a Docusaurus plugin embedded in the docs.

• External LLM clients, developers can connect their preferred client (Claude, ChatGPT, or local models) to the MCP server and access the same assistant capabilities from their own workflow.

- Monthly Gap Report

The assistant logs questions it cannot confidently answer using the available documentation or tools.

A monthly report summarizes:

• frequently unanswered queries

• documentation gaps revealed by integrator questions

• recommended improvements or additions to the docs

This provides continuous feedback about where documentation can be improved.

---

Handover

All work is delivered through production-ready pull requests and repositories, allowing the CoW team to review, merge, and maintain the system within their existing workflow.

Documentation

• Documentation improvements delivered as PRs to the official docs repository

• Includes rewritten sections, quickstarts, examples, and error references

Documentation Validation

• CI validation system delivered either:

  • integrated into the docs repo, or

  • as a separate docs-testing repository (if maintainers prefer separation)

Includes executable artifacts, test manifests, and cross-repo drift detection.

AI Assistant (Track A)

If Track A is implemented, the MCP assistant is delivered as a separate deployable repository with Docker/Kubernetes deployment support.

Operational Notes

Runbooks and setup documentation are included to enable the CoW team to maintain and extend the system independently.

---

3. Budget & Timeline

Commercial Envelope

Scope	Budget	Duration
Core (docs overhaul + 3 quickstarts + validation + cross-repo CI + handover)	$16,500	6 weeks
MCP assistant + gap reports	$6,500	+2 weeks
Full engagement	$23,000	8 weeks

Payment Structure

Milestone	Amount	Deliverable
M1: Kickoff + scope lock	$2,500	Scope map, baseline audit, quickstart skeletons
M2: Documentation delivery	$7,000	All docs sections + 3 quickstart paths + error reference + rate limits
M3: Validation + cross-repo CI	$4,500	Test manifests, executable artifacts, cross-repo dispatch setup
M4: Handover	$2,500	Runbook, ownership notes, final review
M5: MCP assistant	$6,500	MCP server, Docusaurus plugin, monthly gap report template

Core Team Time

Fixed estimate: 10 hours total.

Activity	Hours
Kickoff and scope alignment	2
Technical review of docs sections	3
Quickstart validation	2
Validation and CI review	1.5
Final handover	1.5

Delivery Timeline

Week	Checkpoint
1	Scope map, baseline audit, quickstart skeletons
2–3	Full docs sections: order creation, approvals, quoting, error reference, rate limits
4	3 quickstart paths complete and testable
5	Validation manifests + cross-repo CI setup
6	Handover: runbook, ownership notes, final review
7–8	MCP assistant: server, plugin, gap report template

---

4. Out of Scope

Aligned with RFC exclusions:

1. Solver documentation.

2. CoW AMM docs.

3. MEV Blocker docs.

4. Platform migration unrelated to this integration scope.

5. End-user conceptual rewrites.

[bleu]

Hey all — José from Bleu here. We’ve completed more than a dozen grants with CoW over the past three years — cow-py, four hook dApps, cow-shed, the framework-agnostic SDK, solver infrastructure, and more — and have a few opinions on this RFC. Rather than just share opinions though, we wanted to go ahead and build something to prove the viability and demonstrate the need.

We took the existing docs, restructured them using Diátaxis, migrated to Mintlify, and wrote a bunch of missing content.

The result is here: https://docs.cow.bleu.builders (source code on GitHub).

We’re paying for Mintlify hosting ourselves (USD 250/mo) and all the code is public. CoW DAO is welcome to take over this repo tomorrow at no cost — the content is theirs to use.

To be upfront: we don’t love being dependent on a SaaS provider either. But all the content is open-source Markdown/MDX in a Git repo, so there’s no real lock-in on the content side. If Mintlify disappeared tomorrow, we’d lose the tooling layer but keep every page of content and could redeploy on Docusaurus or any MDX-compatible framework within days. What Mintlify gives us on top is the tooling layer: AI chat, search, analytics, and critically, workflows that can trigger docs updates from PRs and cron jobs. That last part matters — having a process that prompts documentation updates when code changes land is table stakes for keeping docs current, and it’s something we get out of the box instead of building and maintaining ourselves. We think paying a vendor whose full-time job is documentation tooling and developer experience is a better use of money than paying someone to rebuild and maintain all of that from scratch.

What we found and what we built

The current docs have solid foundations — the concepts section, CoW Swap tutorials, and core contract reference are well done. But there are significant gaps for anyone building on top of the protocol rather than just using the UI:

• ComposableCoW + Watch Tower: reference page exists but no tutorials, troubleshooting, or worked examples. Watch Tower has no dedicated docs. Naming is inconsistent across docs and codebase.
• Python SDK: zero documentation on docs.cow.fi.
• API reference: orderbook, driver, and solver render interactive OpenAPI docs but lack surrounding context — no workflow guides, no error handling patterns, no rate limits.
• Error reference, rate limits, fee model: nonexistent or lacking the practical guidance integrators need (blocked Rotki’s accounting integration, came up in 4+ Discord threads).
• Solver tutorials: 6 of 10 source files are drafts that don’t render. The critical pages (create, deploy, test, evaluate) are missing.
• Hooks: no Hook Store docs, no dApp development spec, no worked post-hook examples. We’ve shipped four hook dApps for CoW — these gaps slow developers down.
• Backend services: Services, Flash Loan Router, BFF have no documentation.

Structurally, there’s no information architecture (content follows Docusaurus directory conventions, not developer needs), no persona-based navigation, 9 stale drafts leaving holes in the doc graph, and key content like ERC-1271 signing is comprehensive but buried where the integrators who need it can’t find it.

We sourced these gaps from an audit of all open issues, ~100 closed/merged PRs (including review comment debates) on cowprotocol/docs, the CoW Forum Technical and Knowledge Base categories, and Discord’s #tech-talk channel. Our docs incorporate corrections and domain knowledge from that audit.

We addressed all of these, restructured everything using Diátaxis, and set up Mintlify Workflows that watch 12 repos across cowprotocol and cowdao-grants — opening docs PRs on code changes and running weekly quality/staleness audits. The live site has the full picture.

On Track A vs Track B

We built a RAG PoC over the current docs (demo here). The main takeaway: AI answers are only as good as the underlying content. No model or retrieval trick fixes bad source material.

Much of what Track A describes may already be covered by Mintlify’s native AI features — the live site has contextual AI options on every page (Claude, ChatGPT, Perplexity, Cursor, MCP), built-in AI chat in search with a custom system prompt, Discord/Slack bot deployment, and auto-generated skill.md following the agentskills.io spec. Worth evaluating before committing to a bespoke RAG + FAISS pipeline that will need its own maintenance.

We’d also push back gently on splitting Track A and Track B across different teams. The team writing docs sees what the AI needs to surface, and AI usage data reveals what the docs are missing. Different teams for each will drift apart.

More broadly, we think the bigger gap is that documentation hasn’t been treated as a product — one of the main surface areas CoW has for distribution across developers and integrators. Even if someone builds tooling to auto-generate or auto-update docs, that content still needs to be audited and owned by someone accountable, with process around it. We used AI extensively to generate initial drafts, and even with careful review the content still needs ongoing verification — the repo is public and we welcome feedback and PRs.

How we think about this

Everything we’ve built is live and public. CoW DAO can fork the repo and use it however they want — no charge, no strings.

The RFC describes this as a deliverable — either a deployed system (Track A) or restructured reference pages (Track B). Both framings treat documentation as a project with an end date. In our experience, that’s the pattern that produced the current gaps. Content gets written, ships, and starts decaying the moment the engagement ends. The 9 draft files in the current docs, the missing error references, the SDK page that never grew into a section — none of that happened because someone wrote bad docs. It happened because no one was accountable for docs as an ongoing function after the initial work shipped.

We’d push the council to think about this less as a one-time grant and more as an ongoing responsibility — whoever does this work should be owning it continuously, triaging issues, monitoring where integrators actually get stuck (Discord, forum, BD feedback), and updating content as the protocol evolves. That’s what makes the difference between documentation that works in month one and documentation that still works in month twelve.

We’re obviously biased here — we’ve already built the thing and we’d be happy to keep maintaining it. But regardless of whether it’s us or someone else, we think the council should be evaluating proposals on who’s going to own this long-term, not just who can deliver a Phase 1.

— José, for Bleu (@bleu @yvesfracari @ribeirojose @mendesfabio @brunota20)