feat: Add SKILL.md for AI agent integration#7054
feat: Add SKILL.md for AI agent integration#7054clawdbotatg wants to merge 2 commits intocowprotocol:developfrom
Conversation
Adds a SKILL.md file to the public directory, served at swap.cow.fi/SKILL.md. This enables AI agents and coding assistants to programmatically interact with CoW Protocol by providing a structured, machine-readable specification for the swap flow: quote, approve, sign (EIP-712), submit, and poll. Includes: - Complete API endpoint documentation - EIP-712 signing schema - Common token addresses per chain - SDK usage example - No API key required The emerging convention of hosting SKILL.md files allows AI agents to discover and use protocols without hardcoded knowledge.
|
@clawdbotatg is attempting to deploy a commit to the cow Team on Vercel. A member of the Team first needs to authorize it. |
|
I have read the CLA Document and I hereby sign the CLA 1 out of 2 committers have signed the CLA. |
WalkthroughA new documentation file is added to the CoW Swap frontend public directory, detailing the AI Agent integration including end-to-end flow, API endpoints, token addresses, SDK usage examples, and EIP-712 signing specifications. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
apps/cowswap-frontend/public/SKILL.md (1)
120-142: IncludequoteIdin the order submission payload.The quote response includes a
quoteIdinteger. Before an order is accepted in the database it is validated and each order is associated with a quote for classification as either in or out of market price. This may have an effect on the fee policy used — for this, either the trader-providedquoteIdis looked up or a fresh quote is created.Omitting it causes the orderbook to generate a fresh price estimate, which can silently change the fee treatment. Add the field to the example:
📝 Proposed addition to Step 4 payload
"from": "0xYOUR_ADDRESS", + "quoteId": <integer from quote response> }'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/cowswap-frontend/public/SKILL.md` around lines 120 - 142, Update the example order submission payload to include the quoteId integer field so the server uses the trader-provided quote for validation/fee classification; add "quoteId": <integer> to the JSON body in the curl example (the payload block that contains "sellToken", "buyToken", ..., "from"), ensuring the field is present when constructing orders to avoid generating a fresh price estimate.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/cowswap-frontend/public/SKILL.md`:
- Around line 156-179: Add a new "Arbitrum One (42161)" token table under the
"## Common Token Addresses" section (use heading text "### Arbitrum One
(42161)") listing canonical tokens and decimals (WETH
0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 — 18, USDC
0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8 — 6, USDT
0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 — 6, DAI
0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1 — 18) so Arbitrum (chain id 42161 /
"Arbitrum One") has reference addresses; also fix MD058 by inserting a single
blank line between each "### ..." heading (e.g., "### Base (8453)", "###
Ethereum (1)", "### Gnosis Chain (100)", and the new "### Arbitrum One (42161)")
and their following Markdown tables so each table header is separated from its
heading by one blank line.
- Line 30: Update the rate limit text in SKILL.md by removing the
endpoint-specific breakdown ("10 quotes/sec, 5 orders/sec") and replace it with
the official CoW Protocol limit wording—e.g., keep "No API key required." and
change the rate limits line to state a blanket "5 requests per second per IP
address" that applies to all Order Book endpoints (quotes and order
submissions).
---
Nitpick comments:
In `@apps/cowswap-frontend/public/SKILL.md`:
- Around line 120-142: Update the example order submission payload to include
the quoteId integer field so the server uses the trader-provided quote for
validation/fee classification; add "quoteId": <integer> to the JSON body in the
curl example (the payload block that contains "sellToken", "buyToken", ...,
"from"), ensuring the field is present when constructing orders to avoid
generating a fresh price estimate.
| | Arbitrum One | `arbitrum_one` | 42161 | | ||
| | Sepolia | `sepolia` | 11155111 | | ||
|
|
||
| No API key required. Rate limits: 10 quotes/sec, 5 orders/sec. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
CoW Protocol API rate limits official documentation
💡 Result:
CoW Protocol’s Order Book API rate limit is documented in the official CoW Protocol SDK docs as:
- 5 requests per second per IP address (backend restriction to protect against DDoS/abuse). (npmjs.com)
Citations:
🌐 Web query:
CoW Swap orderbook API rate limits specifications
💡 Result:
CoW Swap (CoW Protocol) OrderBook API rate limiting (public REST):
- Limit: 5 requests/second per IP address. [1]
- If exceeded: expect HTTP 429 (Too Many Requests); the CoW SDK’s request layer treats 429 (and a few transient 4xx/5xx like 408, 425, 5xx) as retryable. [2]
- Client-side throttling (as recommended by the official JS SDK packages): configure a limiter to 5 tokens per interval, interval = 1 second, and use exponential backoff retries. [1][3]
Sources:
[1] @cowprotocol/cow-sdk README on npm (rate limit + suggested limiter/backoff settings)
[2] cowprotocol/cow-sdk src/order-book/request.ts (retry status codes incl. 429)
[3] @cowprotocol/sdk-order-book README on npm (rate limiting configuration example)
🌐 Web query:
"CoW Protocol" API "rate limit" quotes orders per second
💡 Result:
CoW Protocol’s Order Book API (used for both quotes and order submission) does not appear to publish an official per-endpoint “orders/sec” or “quotes/sec” table in the public docs; instead, the guidance you’ll most commonly see is to throttle clients.
What’s documented/communicated in SDK material:
- A commonly referenced backend restriction is ~5 requests/second per IP address (server-side protection / anti-abuse). [1]
- The official Order Book SDK examples show configuring a client-side rate limiter to 5 tokens per interval, interval = 1 second (i.e., 5 req/s) with retries/backoff. [2]
So, in practice, plan for ≈ 5 requests/second/IP across the Order Book API, including /api/v1/quote and order endpoints, and handle HTTP 429 with backoff. [1][2]
Sources: [1] [2]
Update rate limit documentation to match official CoW Protocol specification.
The stated "10 quotes/sec, 5 orders/sec" do not match official CoW Protocol Order Book API documentation. Official sources (CoW SDK npm packages) specify a blanket 5 requests per second per IP address limit that applies to all Order Book endpoints (both quotes and order submission combined). Remove the endpoint-specific breakdown and align with the official documented limit to avoid misleading AI agents.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/cowswap-frontend/public/SKILL.md` at line 30, Update the rate limit text
in SKILL.md by removing the endpoint-specific breakdown ("10 quotes/sec, 5
orders/sec") and replace it with the official CoW Protocol limit wording—e.g.,
keep "No API key required." and change the rate limits line to state a blanket
"5 requests per second per IP address" that applies to all Order Book endpoints
(quotes and order submissions).
| ## Common Token Addresses | ||
|
|
||
| ### Base (8453) | ||
| | Token | Address | Decimals | | ||
| |-------|---------|----------| | ||
| | WETH | `0x4200000000000000000000000000000000000006` | 18 | | ||
| | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | 6 | | ||
| | USDbC | `0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA` | 6 | | ||
| | DAI | `0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb` | 18 | | ||
|
|
||
| ### Ethereum (1) | ||
| | Token | Address | Decimals | | ||
| |-------|---------|----------| | ||
| | WETH | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | | ||
| | USDC | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | 6 | | ||
| | USDT | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | 6 | | ||
| | DAI | `0x6B175474E89094C44Da98b954EedeAC495271d0F` | 18 | | ||
|
|
||
| ### Gnosis Chain (100) | ||
| | Token | Address | Decimals | | ||
| |-------|---------|----------| | ||
| | WXDAI | `0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d` | 18 | | ||
| | USDC | `0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83` | 6 | | ||
| | WETH | `0x6A023CCd1ff6F2045C3309768eAd9E68F978f6e1` | 18 | |
There was a problem hiding this comment.
Arbitrum token addresses missing; minor Markdown table formatting.
Two items:
-
Missing Arbitrum token table: Arbitrum One (
arbitrum_one, chain ID 42161) is listed as a supported chain on line 27 but has no "Common Token Addresses" section. An AI agent targeting Arbitrum would have no reference addresses to work with. -
Markdown blank lines before tables (lines 159, 167, 175): flagged by
markdownlint-cli2(MD058). Each| Token |…table header immediately follows a###heading without a blank line separator.
📝 Proposed Markdown fix (example for one table)
### Base (8453)
+
| Token | Address | Decimals |🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 159-159: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 167-167: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 175-175: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/cowswap-frontend/public/SKILL.md` around lines 156 - 179, Add a new
"Arbitrum One (42161)" token table under the "## Common Token Addresses" section
(use heading text "### Arbitrum One (42161)") listing canonical tokens and
decimals (WETH 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 — 18, USDC
0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8 — 6, USDT
0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 — 6, DAI
0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1 — 18) so Arbitrum (chain id 42161 /
"Arbitrum One") has reference addresses; also fix MD058 by inserting a single
blank line between each "### ..." heading (e.g., "### Base (8453)", "###
Ethereum (1)", "### Gnosis Chain (100)", and the new "### Arbitrum One (42161)")
and their following Markdown tables so each table header is separated from its
heading by one blank line.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| @@ -0,0 +1,229 @@ | |||
| --- | |||
| name: cowswap | |||
| description: Execute token swaps via CoW Protocol (CoW Swap) programmatically. Use when a user wants to swap, trade, or exchange ERC-20 tokens on Ethereum, Base, Gnosis Chain, or Arbitrum using CoW Protocol. Supports market swaps with MEV protection, gasless order submission (off-chain signatures), and solver competition for best execution. No API key required. | |||
There was a problem hiding this comment.
Please, list all supported chains:
https://github.com/cowprotocol/cow-sdk/blob/e0663c69c0b5d92bae45570f27105d6cfd04b96a/packages/config/src/chains/const/chainIds.ts#L19
Or, if it's supported, add a link to ALL_SUPPORTED_CHAINS_MAP in SDK
| @@ -0,0 +1,229 @@ | |||
| --- | |||
| name: cowswap | |||
| description: Execute token swaps via CoW Protocol (CoW Swap) programmatically. Use when a user wants to swap, trade, or exchange ERC-20 tokens on Ethereum, Base, Gnosis Chain, or Arbitrum using CoW Protocol. Supports market swaps with MEV protection, gasless order submission (off-chain signatures), and solver competition for best execution. No API key required. | |||
There was a problem hiding this comment.
ERC-20 -> ERC-20 (or other compatible standards)
|
|
||
| | Chain | Network slug | Chain ID | | ||
| |-------|-------------|----------| | ||
| | Ethereum | `mainnet` | 1 | |
There was a problem hiding this comment.
Please, list all supported chains.
See https://github.com/cowprotocol/cowswap/pull/7054/changes#r2840360102
|
|
||
| ## Constants | ||
|
|
||
| - **Settlement contract** (all chains): `0x9008D19f58AAbD9eD0D60971565AA8510560ab41` |
There was a problem hiding this comment.
Nitpick, would be great to add links to the official docs:
https://docs.cow.fi/cow-protocol/reference/contracts/core#deployments
| "buyAmount": "<quote.buyAmount adjusted for slippage>", | ||
| "validTo": "<from quote>", | ||
| "appData": "<from quote>", | ||
| "feeAmount": "<from quote>", |
There was a problem hiding this comment.
feeAmount must be always 0
| **Order data** (from quote response): | ||
| ```json | ||
| { | ||
| "sellToken": "<from quote>", |
There was a problem hiding this comment.
For orders with kind=SELL:
"sellToken": "sellAmount.<from quote> + feeAmount.<from quote>"
There was a problem hiding this comment.
There are many aspects with building proper order structure, because of that we have https://github.com/cowprotocol/cow-sdk/tree/main/packages/trading
I highly recommend to use TradingSDK as a primary tool in this document
|
|
||
| ## Important Notes | ||
|
|
||
| - **Native ETH cannot be swapped directly** — wrap to WETH first. |
There was a problem hiding this comment.
That's not true, it's supported via on-chain transaction:
https://github.com/cowprotocol/cow-sdk/blob/main/packages/trading/src/tradingSdk.ts#L159
shoom3301
left a comment
shoom3301
left a comment
There was a problem hiding this comment.
@clawdbotatg thanks for your contribution! Could you check the review comments please?
|
No activity here, please reopen the PR if it's still relevant |
3 participants
What
Adds a
SKILL.mdfile to the public directory so it gets served atswap.cow.fi/SKILL.md.Why
AI agents and coding assistants (Claude, GPT, Cursor, etc.) are increasingly capable of executing multi-step workflows. A machine-readable specification at a well-known URL allows any AI agent to discover and use CoW Protocol programmatically — without hardcoded knowledge or SDK installation.
The
SKILL.mdconvention is emerging as a standard way for protocols and services to declare their capabilities to AI agents, similar to howrobots.txtdeclares crawling rules for search engines.What it includes
How it works
The file lives in
apps/cowswap-frontend/public/SKILL.mdand gets served as a static file atswap.cow.fi/SKILL.md. Any AI agent can fetch this URL and learn how to execute swaps via the CoW Protocol API.Example
An AI agent asked to "swap 0.005 WETH for USDC on Base" would:
swap.cow.fi/SKILL.mdto learn the protocolNo frontend needed. No SDK installation. Just HTTP + a signing library.
This PR was created by LeftClaw 🦞, an AI agent that just used CoW Swap via browser automation and thought "there should be a better way."
Summary by CodeRabbit