VeloraDEX · andriy-shymkiv · Jun 22, 2026
diff --git a/cli/install.mdx b/cli/install.mdx
@@ -0,0 +1,90 @@
+---
+title: "Install the Velora CLI"
+sidebarTitle: "Install"
+description: "Install @velora-dex/cli and run your first swap quote from the terminal in under a minute."
+keywords: ["cli", "install", "npm", "npx", "quickstart"]
+---
+
+The Velora CLI is published as [`@velora-dex/cli`](https://www.npmjs.com/package/@velora-dex/cli) and installs a `velora` binary. It needs **Node 22 or newer**.
+
+## Run it without installing
+
+Use `npx` (or your package manager's equivalent) to run the latest version on demand:
+
+```bash
+npx @velora-dex/cli quote --src-token DAI --dest-token USDC --amount 1000
+```
+
+This is the fastest way to try the CLI or use it in a one-off script.
+
+## Install globally
+
+For repeated use, install it once and call `velora` directly:
+
+<CodeGroup>
+
+```bash pnpm
+pnpm add -g @velora-dex/cli
+```
+
+```bash npm
+npm install -g @velora-dex/cli
+```
+
+```bash yarn
+yarn global add @velora-dex/cli
+```
+
+</CodeGroup>
+
+Then:
+
+```bash
+velora quote --src-token DAI --dest-token USDC --amount 1000
+```
+
+## Your first quote
+
+Price 1,000 DAI to USDC on Ethereum and print a summary:
+
+```bash
+velora quote --src-token DAI --dest-token USDC --amount 1000
+```
+
+By default the CLI requests `--mode ALL`, so the API returns a [Delta](/delta/overview) intent when one is available and falls back to a [Market](/market/overview) route otherwise. The summary's `path:` line tells you which one came back.
+
+To get the full response for scripting, add `--json`:
+
+```bash
+velora quote --src-token DAI --dest-token USDC --amount 1000 --json | jq
+```
+
+## Set a partner identifier
+
+Every quote carries a `partner` string for attribution. The CLI defaults to `velora-cli`; pass your own app or project name with `--partner`:
+
+```bash
+velora quote --src-token DAI --dest-token USDC --amount 1000 --partner my-app-name
+```
+
+Replace `my-app-name` with your own identifier. `partner` is a free, no-signup attribution string, not a secret API key.
+
+## Add an API key
+
+For higher [rate limits](/integrate/rate-limits), pass a [Pro API key](/overview/pro-api-accounts) with `--api-key`, or set the `VELORA_API_KEY` environment variable and the CLI picks it up automatically:
+
+```bash
+export VELORA_API_KEY="<your-api-key>"
+velora quote --src-token DAI --dest-token USDC --amount 1000
+```
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Get Quote" icon="terminal" href="/cli/quote">
+    Every flag, the `--payload` file, and crosschain quotes.
+  </Card>
+  <Card title="SDK" icon="cube" href="/sdk/overview">
+    Build and submit orders programmatically with `@velora-dex/sdk`.
+  </Card>
+</CardGroup>
diff --git a/cli/overview.mdx b/cli/overview.mdx
@@ -0,0 +1,65 @@
+---
+title: "Velora CLI"
+sidebarTitle: "Overview"
+description: "Fetch Velora swap quotes from your terminal with @velora-dex/cli, a thin command-line wrapper over the Velora SDK."
+keywords: ["cli", "command line", "terminal", "quote", "swap price"]
+---
+
+`@velora-dex/cli` is a command-line tool for Velora. It wraps the [Velora SDK](/sdk/overview) so you can pull a swap quote straight from your terminal, without writing any code. Today it ships one command, [`quote`](/cli/quote), which prices a swap against the live Velora API and prints either a readable summary or the raw JSON.
+
+Reach for the CLI when you want to check a price quickly, script a quote into a shell pipeline, or sanity-check the API while you build a larger integration. For anything that signs or submits an order, use the [SDK](/sdk/overview) or the [API](/integrate/api) directly.
+
+## What you get
+
+<CardGroup cols={3}>
+  <Card title="Symbols or addresses" icon="coins">
+    Pass tokens by symbol (`DAI`, `USDC`) or address. Decimals resolve from the
+    bundled token lists, so you rarely set them by hand.
+  </Card>
+  <Card title="Delta and Market" icon="bolt">
+    One command prices both. With `--mode ALL` the API returns a Delta intent or
+    a Market route, and notes which path came back.
+  </Card>
+  <Card title="Pipe-friendly" icon="terminal">
+    `--json` prints the raw response to stdout, so you can redirect it to a file
+    or pipe it into `jq`.
+  </Card>
+</CardGroup>
+
+## Quick example
+
+Quote 1,000 DAI to USDC on Ethereum:
+
+```bash
+velora quote --src-token DAI --dest-token USDC --amount 1000
+```
+
+```
+Quote — Ethereum (chainId 1)  path: DELTA (gasless intent)
+  You pay:     1000.0 ($1000.00)  0x6b175474e89094c44da98b954eedeac495271d0f
+  You receive: 999.82 ($999.82)   0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
+  Gas fee:     n/a
+```
+
+Add `--json` to get the full API response instead of the summary.
+
+## How it works
+
+The CLI resolves your tokens and amount, calls the same `getQuote` method the SDK exposes, and renders the result:
+
+- `--amount` is given in **human units** (e.g. `1.5`), not wei. The CLI converts it using the resolved token's decimals.
+- Tokens accept a symbol or an address, including the native placeholder `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` or the chain's native currency symbol (`ETH`, `MATIC`).
+- Token lists are fetched once and cached on disk for 24 hours, so symbol lookups are instant after the first run.
+
+It supports nine chains: Ethereum, Polygon, BSC, Avalanche, Arbitrum, Optimism, Base, Gnosis, and Unichain. Source chain defaults to Ethereum (`1`).
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Install" icon="download" href="/cli/install">
+    Add `@velora-dex/cli` and run your first quote.
+  </Card>
+  <Card title="Get Quote" icon="terminal" href="/cli/quote">
+    Every flag, the `--payload` file, and the JSON output.
+  </Card>
+</CardGroup>
diff --git a/cli/quote.mdx b/cli/quote.mdx
@@ -0,0 +1,122 @@
+---
+title: "velora quote"
+sidebarTitle: "Get Quote"
+description: "Reference for the velora quote command: fetch a Delta or Market swap price from the terminal, with every flag and the reusable --payload file."
+keywords: ["cli", "quote", "swap price", "command reference", "payload"]
+---
+
+`velora quote` fetches a swap price from the Velora API and prints a readable summary, or the raw JSON with `--json`. It prices both [Delta](/delta/overview) and [Market](/market/overview); with the default `--mode ALL` the API returns whichever applies.
+
+```bash
+velora quote --src-token DAI --dest-token USDC --amount 1000
+```
+
+## Tokens and amounts
+
+Each token flag accepts a **symbol** or an **address**:
+
+- A symbol (`DAI`, `USDC`) resolves against the bundled token lists for the chain, and its decimals fill in automatically.
+- An address is used as-is. This includes the native placeholder `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` and the chain's native currency symbol (`ETH`, `MATIC`), both of which map to the native token.
+
+`--amount` is in **human units** (e.g. `1.5`), not wei. For a `SELL` it is the source amount; for a `BUY` it is the destination amount. The CLI converts it using the relevant token's decimals.
+
+When a token isn't in the lists, set its decimals explicitly with `--src-decimals` / `--dest-decimals`; otherwise the command errors rather than guessing.
+
+```bash
+# By address, on a specific chain
+velora quote --chain 1 \
+  --src-token 0x6b175474e89094c44da98b954eedeac495271d0f \
+  --dest-token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --amount 1000
+```
+
+## Options
+
+Multi-word flags also accept a **camelCase alias** (e.g. `--srcToken` for `--src-token`), matching the `--payload` key names.
+
+| Flag                          | Required | Description                                                             |
+| ----------------------------- | -------- | ----------------------------------------------------------------------- |
+| `--amount <amount>`           | yes      | Amount in human units — source amount for `SELL`, dest amount for `BUY` |
+| `--src-token <token>`         | yes      | Source token symbol or address (or native placeholder)                  |
+| `--dest-token <token>`        | yes      | Destination token symbol or address                                     |
+| `--src-decimals <n>`          | no       | Source token decimals (resolved from the token lists if omitted)        |
+| `--dest-decimals <n>`         | no       | Destination token decimals (resolved from the token lists if omitted)   |
+| `--chain <id>`                | no       | Source chain id (default `1`, Ethereum)                                 |
+| `--side <SELL\|BUY>`          | no       | Trade side (default `SELL`)                                             |
+| `--mode <DELTA\|MARKET\|ALL>` | no       | Pricing mode (default `ALL`)                                            |
+| `--user-address <address>`    | no       | End-user wallet address                                                 |
+| `--partner <name>`            | no       | Partner identifier (default `velora-cli`)                               |
+| `--partner-fee-bps <bps>`     | no       | Partner fee in basis points (0–200, e.g. `50` = 0.5%)                   |
+| `--max-impact <pct>`          | no       | Max acceptable price impact, in percent                                 |
+| `--max-usd-impact <usd>`      | no       | Max acceptable price impact, in USD                                     |
+| `--dest-chain <id>`           | no       | Destination chain id for a crosschain quote (Delta-only)                |
+| `--api-url <url>`             | no       | Override the Velora API base URL                                        |
+| `--api-key <key>`             | no       | API key (defaults to the `VELORA_API_KEY` env var)                      |
+| `--payload <file>`            | no       | JSON file of params; flags override its values                          |
+| `--json`                      | no       | Print the raw API response instead of a summary                         |
+
+<Note>
+`--side` is matched case-insensitively and the documented forms are uppercase (`SELL`, `BUY`); the same goes for `--mode` (`DELTA`, `MARKET`, `ALL`).
+</Note>
+
+## Pricing modes
+
+With `--mode ALL` (the default) the API returns **one** shape: a Delta intent when one is available, or a Market route otherwise. The summary's `path:` line tells you which came back, and notes when Delta was unavailable and the quote fell back to Market.
+
+Force a single mode when you need it:
+
+```bash
+# Gasless Delta intent only
+velora quote --src-token DAI --dest-token USDC --amount 1000 --mode DELTA
+
+# On-chain Market route only
+velora quote --src-token DAI --dest-token USDC --amount 1000 --mode MARKET
+```
+
+## Crosschain quotes
+
+Pass `--dest-chain` (differing from `--chain`) for a crosschain quote. These are Delta-only, so the command rejects `--mode MARKET` for them.
+
+```bash
+# 1,000 USDC on Ethereum → USDC on Arbitrum
+velora quote --chain 1 --dest-chain 42161 \
+  --src-token USDC --dest-token USDC --amount 1000 --mode DELTA
+```
+
+## Reusable params with `--payload`
+
+`--payload <file>` reads a JSON object whose **camelCase** keys mirror the flags, so you can pin the params that rarely change (like `userAddress`, `apiKey`, `partner`) in a file and pass only the trade specifics on the command line. A flag, when given, overrides the matching payload value; the payload fills in for any omitted flag.
+
+```json trade.json
+{
+  "partner": "my-app-name",
+  "userAddress": "0x1111111111111111111111111111111111111111",
+  "apiKey": "<your-api-key>",
+  "srcToken": "DAI",
+  "destToken": "USDC"
+}
+```
+
+```bash
+velora quote --payload trade.json --amount 1000
+```
+
+Allowed keys: `amount`, `srcToken`, `destToken`, `srcDecimals`, `destDecimals`, `chain`, `destChain`, `side`, `mode`, `userAddress`, `partner`, `partnerFeeBps`, `maxImpact`, `maxUsdImpact`, `apiUrl`, `apiKey`. Values may be strings, numbers, or booleans; unknown keys are rejected so typos surface early. (`maxUsdImpact` maps to the API's `maxUSDImpact`.)
+
+## JSON output
+
+`--json` prints the raw API response to stdout, so you can redirect it or pipe it on:
+
+```bash
+# Save to a file
+velora quote --src-token DAI --dest-token USDC --amount 1000 --json > quote.json
+
+# Pipe into jq
+velora quote --src-token DAI --dest-token USDC --amount 1000 --json | jq '.delta.destAmount'
+```
+
+## Related pages
+
+- [Install](/cli/install): set up the `velora` binary and an API key.
+- [SDK](/sdk/overview): the library the CLI wraps, for building and submitting orders.
+- [Delta API quote](/api-reference/delta/quote): the underlying endpoint and its full response shape.
diff --git a/docs.json b/docs.json
@@ -151,6 +151,14 @@
                 ]
               }
             ]
+          },
+          {
+            "group": "CLI",
+            "pages": [
+              "cli/overview",
+              "cli/install",
+              "cli/quote"
+            ]
           }
         ]
       },