https://github.com/cowprotocol/cowswap
🐮 CowSwap: First CoW Protocol UI
https://github.com/cowprotocol/cowswap
Last synced: 20 days ago
JSON representation
🐮 CowSwap: First CoW Protocol UI
- Host: GitHub
- URL: https://github.com/cowprotocol/cowswap
- Owner: cowprotocol
- License: gpl-3.0
- Created: 2022-03-29T11:51:40.000Z (about 4 years ago)
- Default Branch: develop
- Last Pushed: 2026-04-01T21:45:01.000Z (2 months ago)
- Last Synced: 2026-04-01T22:17:20.174Z (2 months ago)
- Language: TypeScript
- Homepage: https://swap.cow.fi/
- Size: 190 MB
- Stars: 179
- Watchers: 10
- Forks: 166
- Open Issues: 234
-
Metadata Files:
- Readme: README.md
- Changelog: changes.txt
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/cowprotocol/cowswap/actions/workflows/ci.yml?query=workflow%3ACI)
CoW Swap is the first trading interface built on top of CoW Protocol.
It allows you to buy and sell tokens using gasless orders that are settled
peer-to-peer among its users or into any on-chain liquidity source while
providing MEV protection.
| **Platform** | **Link** |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| 🐮 **CoW Swap** 🐮 | [swap.cow.fi](https://swap.cow.fi/) |
| CoW Swap (IPFS) | Every release is deployed automatically to IPFS ([Releases](https://github.com/cowprotocol/cowswap/releases)) |
| CoW Swap (ENS) | [ens://cowswap.eth](ens://cowswap.eth) or ([cowswap.eth.limo](https://cowswap.eth.limo)) |
| CoW Protocol | [cow.fi](https://cow.fi) |
| Docs | [docs.cow.fi](https://docs.cow.fi) |
| Governance (Snapshot) | [snapshot.org/#/cow.eth](https://snapshot.org/#/cow.eth) |
| Stats | [dune.com/cowprotocol/cowswap](https://dune.com/cowprotocol/cow-swap-home) |
| X/Twitter | [@CoWSwap](https://twitter.com/CoWSwap) |
| Discord | [discord.com/invite/cowprotocol](https://discord.com/invite/cowprotocol) |
| Forum | [forum.cow.fi](https://forum.cow.fi) |
# 🐮 Run CoW Swap
First install Dependencies:
```bash
pnpm install
```
To upgrade `@cowprotocol/cow-sdk` and all `@cowprotocol/sdk-*` packages to the latest published versions:
```bash
pnpm upgrade-sdk-latest
pnpm install
```
Or, if you want to use `@cowprotocol/sdk` preview versions like `"@cowprotocol/cow-sdk": "7.0.4-pr-546-c04641f0.0"`, then:
- run `pnpm upgrade-sdk-preview https://github.com/cowprotocol/cow-sdk/pull/787` with a link to SDK PR with deployed previews
- run `PACKAGE_READ_AUTH_TOKEN=XXX pnpm run install:sdk-preview` instead of just `pnpm install`
- the token must be generated in GitHub with `read:packages` permissions
## Run
Start CoW Swap on `http://localhost:3000`
```bash
pnpm start
```
Environment selection for `cowswap-frontend` is configured explicitly via `REACT_APP_ENVIRONMENT`
in the app-level `.env.*` files:
- Supported values:
`local`, `development`, `pr`, `staging`, `production`, `ens`
- `apps/cowswap-frontend/.env.development` -> `local`
- `apps/cowswap-frontend/.env.dev` -> `development`
- `apps/cowswap-frontend/.env.staging` -> `staging`
- `apps/cowswap-frontend/.env.production` -> `production`
## Build
Build the project. The static files will be generated in the `build` folder.
```bash
pnpm run build
```
## Unit testing
```bash
pnpm run test
```
# 🔎 Explorer
Start the Explorer on
[Read more about the Explorer](apps/explorer/README.md)
### Start
```bash
pnpm run start:explorer
```
Explorer environment selection is configured explicitly via `REACT_APP_ENVIRONMENT`.
See [apps/explorer/.env.example](apps/explorer/.env.example).
### Build
```bash
pnpm run build:explorer
```
# 🐄 cow.fi
Start cow.fi on
### Start
```bash
pnpm run start:cowfi
```
`cow-fi` no longer infers its environment from the hostname. Set `NEXT_PUBLIC_ENVIRONMENT`
explicitly. See [apps/cow-fi/.env.example](apps/cow-fi/.env.example).
### Build
```bash
pnpm run build:cowfi
```
# 🖼️ Widget Configurator
Start the Widget Configurator on
```bash
# Start
pnpm run start:widget
# Build
pnpm run build:widget
```
# 🌌 Cosmos UI Library
Start the Cosmos UI Library on
```bash
pnpm run cosmos
```
# 🤓 Development
## Integration test
> ⚠️ To run the tests. Make sure you add the required environment variables to
> your root `.env.local` file with:
>
> - `CYPRESS_INTEGRATION_TEST_PRIVATE_KEY=`: Private key
> - `CYPRESS_INTEGRATION_TESTS_INFURA_KEY=`: Infura key
> - `CYPRESS_INTEGRATION_TESTS_ALCHEMY_KEY=`: Alchemy key (preferred if both are set)
To launch it with our development server (so you have live-reloading):
```bash
# Terminal 1
pnpm run start
# Terminal 2
pnpm run e2e
```
If we want to use the Cypress UI, with the production build:
```bash
# Terminal 1
npx nx run cowswap-frontend:serve-static --port 3000
# Terminal 2
pnpm run e2e:open
```
## Analyze build
Analyze CoW Swap bundle:
```bash
# Use one of the following templates: "sunburst" | "treemap" | "network" | "raw-data" | "list";
ANALYZE_BUNDLE=true ANALYZE_BUNDLE_TEMPLATE=sunburst pnpm run build
```
# ⚙️ Configuration
## RPC Endpoints
You should set your own RPC endpoints.
One simple way to do this, is by defining your own `REACT_APP_INFURA_KEY`
environment var.
Alternatively you can define the RPC URLs directly with the following
environment variables:
```ini
REACT_APP_NETWORK_URL_1: https://...
REACT_APP_NETWORK_URL_56: https://...
REACT_APP_NETWORK_URL_100: https://rpc.gnosis.gateway.fm
REACT_APP_NETWORK_URL_137: https://...
REACT_APP_NETWORK_URL_8453: https://...
REACT_APP_NETWORK_URL_9745: https://rpc.plasma.to
REACT_APP_NETWORK_URL_42161: https://...
REACT_APP_NETWORK_URL_43114: https://...
REACT_APP_NETWORK_URL_57073: https://rpc-ten.inkonchain.com
REACT_APP_NETWORK_URL_59144: https://rpc.linea.build
REACT_APP_NETWORK_URL_11155111: https://...
```
Additionally, if you plan to run the integration tests locally you must define:
```ini
INTEGRATION_TESTS_INFURA_KEY: YOUR_INFURA_KEY
INTEGRATION_TESTS_PRIVATE_KEY: YOUR_TEST_WALLET_PRIVATE_KEY
```
## Orderbook API Endpoints
Fee quote requests and posting orders are sent to the Orderbook API. This API
has the responsibility of collecting orders and handing them to the solvers.
The reference implementation of the API is
[CoW Protocol Services](https://github.com/cowprotocol/services).
The API endpoint is configured using the environment variable
`REACT_APP_ORDER_BOOK_URLS`:
```ini
REACT_APP_ORDER_BOOK_URLS='{"1":"https://YOUR_HOST","100":"https://YOUR_HOST","5":"https://YOUR_HOST"}
```
## BFF API Endpoints (Backend for Frontend)
The BFF API is a helper API that provides some additional data to the frontend.
It is a API that is used to enhance the frontend experience enabling some
features. It is not consider a required API for CoW Swap core functionality, the
app will still allow the user to place order and will have some fallback logics
in case this API is not available.
The reference implementation of the API is
[BFF (Backend For Frontend)](https://github.com/cowprotocol/bff).
The API endpoint is configured using the environment variable
`REACT_APP_BFF_BASE_URL`:
```ini
REACT_APP_BFF_BASE_URL=https://bff.cow.fi
```
## CMS API Endpoints (Content Management System)
The CMS API is a helper API that provides some additional content to the frontend.
It is not considered a required API for CoW Swap core functionality, the
app will still allow the user to place orders and will have some fallback logic
in case this API is not available.
The reference implementation of the API is
[CMS API](https://github.com/cowprotocol/cms).
The API endpoint is configured using the environment variable
`REACT_APP_CMS_BASE_URL`:
```ini
REACT_APP_CMS_BASE_URL=https://cms.cow.fi/api
```
## Price feeds
CoW Swap tries to find the best price available on-chain using some price feeds.
All price feeds are enabled by default, but they can be individually disabled by
using an environment variable:
| Name | Environment variable | Type | Description |
| --------- | ------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------ |
| **1inch** | `REACT_APP_PRICE_FEED_1INCH_ENABLED` | `boolean` (default = `true`) | [Paraswap](https://1inch.exchange) price estimation. Used for all price estimations. |
| **0x** | `REACT_APP_PRICE_FEED_0X_ENABLED` | `boolean` (default = `true`) | [0x](https://0x.org/) price estimation. Used for all price estimation. |
## Metadata attached to orders (AppData)
The app will attach some metadata to all orders.
This metadata will be sent to the smart contract as a hexadecimal value in an
order field called `AppData`. This value comes from hashing the content of a
metadata JSON containing some information about the trade (using `keccak256` on
the `UTF-8` bytes).
The format of the JSON follows the format defined in
[@cowprotocol/sdk-app-data](https://www.npmjs.com/package/@cowprotocol/sdk-app-data).
To set your own `AppData`, change `REACT_APP_FULL_APP_DATA_`
environment variable. For more details, check out the environment file (<.env>)
# 🔎 SEO
## Sitemap
`pnpm run build:cowfi` also generates `./sitemap.xml` file.
See [next-sitemap.config.js](apps/cow-fi/next-sitemap.config.js)
# 🔫 Troubleshooting
## Service worker
In case of problems with the service worker cache you force a reset using
[emergency.js](apps/cowswap-frontend/public/emergency.js) The plan:
1. `const resetCacheInCaseOfEmergency = false` - change `false` to `true`
2. Deploy a new version to production
`emergency.js` is not cached by browser and loaded before all.
## Vercel preview build
Each app’s `vercel.json` uses `cd ../..` then **`npx pnpm@10.30.3`** so installs match root **`packageManager`** and avoid Vercel’s default **pnpm 9** (which can trigger `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH` with this lockfile).
**Project settings that must line up (if deploys fail for unclear reasons):**
1. **Root Directory** for that Vercel project should be the app folder (e.g. `apps/cow-fi`). If it is the monorepo root instead, `cd ../..` is wrong and install reads the wrong tree.
2. **Build & Development →** no **Install Command** / **Build Command** override in the dashboard that replaces `vercel.json` (or align them with the repo).
3. **Node.js version** on Vercel should be current LTS (Corepack / `npx` expect a recent Node).
4. **`ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`:** run `pnpm install` locally with **pnpm 10.30.3**, commit any `pnpm-lock.yaml` change, and ensure root `package.json` `pnpm.*` config was not edited without reinstalling.
5. **Ignored Build Step:** use `node tools/scripts/ignore-build-step.js --app=…` — do not use a broken one-line `[ … || … ]` `sh` test (see below).
Since this repo includes multiple apps, we do not want to build all of them on each PR because it causes long build queues in Vercel.
Some apps (see the list below) are not required to be built on each PR so we run them only a PR is labeled with a specific label.
This label is defined in the project settings on Vercel in `Settings`/`Git`/`Ignored Build Step` script.
Use the Node script below (do **not** use a one-line `sh`/`bash` test with `[ ... || ... ]` inside a single `[` — POSIX `[` does not support `||` there, which breaks branch names like `feature/foo` and logs `[: missing \`]'`).
For example, the label for the widget-configurator is `preview-widget-cfg`:
```
node tools/scripts/ignore-build-step.js --app=preview-widget-cfg
```
List of applications and their labels:
- widget-configurator: `preview-widget-cfg`
- cosmos: `preview-cosmos`
- sdk-tools: `preview-sdk-tools`
# 📚 Technical Documentation
1. [Oveall Architecture](docs/architecture-overview.md)
2. [Amounts formatting](libs/common-utils/src/amountFormat/README.md)
3. [ABIs](libs/abis/README.md)