diff --git a/cli/install.mdx b/cli/install.mdx new file mode 100644 index 0000000..b7ddafd --- /dev/null +++ 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: + + + +```bash pnpm +pnpm add -g @velora-dex/cli +``` + +```bash npm +npm install -g @velora-dex/cli +``` + +```bash yarn +yarn global add @velora-dex/cli +``` + + + +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="" +velora quote --src-token DAI --dest-token USDC --amount 1000 +``` + +## Next steps + + + + Every flag, the `--payload` file, and crosschain quotes. + + + Build and submit orders programmatically with `@velora-dex/sdk`. + + diff --git a/cli/overview.mdx b/cli/overview.mdx new file mode 100644 index 0000000..169e31a --- /dev/null +++ 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 + + + + Pass tokens by symbol (`DAI`, `USDC`) or address. Decimals resolve from the + bundled token lists, so you rarely set them by hand. + + + One command prices both. With `--mode ALL` the API returns a Delta intent or + a Market route, and notes which path came back. + + + `--json` prints the raw response to stdout, so you can redirect it to a file + or pipe it into `jq`. + + + +## 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 + + + + Add `@velora-dex/cli` and run your first quote. + + + Every flag, the `--payload` file, and the JSON output. + + diff --git a/cli/quote.mdx b/cli/quote.mdx new file mode 100644 index 0000000..78bc043 --- /dev/null +++ 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 ` | yes | Amount in human units — source amount for `SELL`, dest amount for `BUY` | +| `--src-token ` | yes | Source token symbol or address (or native placeholder) | +| `--dest-token ` | yes | Destination token symbol or address | +| `--src-decimals ` | no | Source token decimals (resolved from the token lists if omitted) | +| `--dest-decimals ` | no | Destination token decimals (resolved from the token lists if omitted) | +| `--chain ` | no | Source chain id (default `1`, Ethereum) | +| `--side ` | no | Trade side (default `SELL`) | +| `--mode ` | no | Pricing mode (default `ALL`) | +| `--user-address
` | no | End-user wallet address | +| `--partner ` | no | Partner identifier (default `velora-cli`) | +| `--partner-fee-bps ` | no | Partner fee in basis points (0–200, e.g. `50` = 0.5%) | +| `--max-impact ` | no | Max acceptable price impact, in percent | +| `--max-usd-impact ` | no | Max acceptable price impact, in USD | +| `--dest-chain ` | no | Destination chain id for a crosschain quote (Delta-only) | +| `--api-url ` | no | Override the Velora API base URL | +| `--api-key ` | no | API key (defaults to the `VELORA_API_KEY` env var) | +| `--payload ` | no | JSON file of params; flags override its values | +| `--json` | no | Print the raw API response instead of a summary | + + +`--side` is matched case-insensitively and the documented forms are uppercase (`SELL`, `BUY`); the same goes for `--mode` (`DELTA`, `MARKET`, `ALL`). + + +## 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 ` 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": "", + "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 index 5fc2fef..9276c8f 100644 --- a/docs.json +++ b/docs.json @@ -151,6 +151,14 @@ ] } ] + }, + { + "group": "CLI", + "pages": [ + "cli/overview", + "cli/install", + "cli/quote" + ] } ] },