From a58183f9ed3f70905c310de9bd639a8745454875 Mon Sep 17 00:00:00 2001 From: Gustavo Gonzalez Date: Tue, 24 Feb 2026 14:36:39 -0400 Subject: [PATCH 1/5] docs: add mintlify site, CI checks, and public docs refinements --- .github/workflows/docs.yml | 35 +++++++ .gitignore | 3 +- AGENTS.md | 9 +- CHANGELOG.md | 4 +- README.md | 17 ++++ agents/overview.mdx | 41 ++++++++ agents/reliability-patterns.mdx | 36 +++++++ agents/schema-driven.mdx | 40 ++++++++ assets/docs-wordmark-dark.svg | 3 + assets/docs-wordmark-light.svg | 3 + concepts/config-and-cache.mdx | 60 ++++++++++++ concepts/ids-and-amounts.mdx | 51 ++++++++++ concepts/output-contract.mdx | 66 +++++++++++++ concepts/providers-and-auth.mdx | 45 +++++++++ docs.json | 119 +++++++++++++++++++++++ guides/bridge.mdx | 41 ++++++++ guides/examples-cookbook.mdx | 73 ++++++++++++++ guides/lending.mdx | 41 ++++++++ guides/market-discovery.mdx | 43 ++++++++ guides/swap.mdx | 36 +++++++ guides/yield.mdx | 47 +++++++++ index.mdx | 62 ++++++++++++ installation.mdx | 59 +++++++++++ quickstart.mdx | 65 +++++++++++++ reference/bridge-and-swap-commands.mdx | 71 ++++++++++++++ reference/chain-aliases.mdx | 36 +++++++ reference/commands-overview.mdx | 48 +++++++++ reference/envelope-schema.mdx | 44 +++++++++ reference/exit-codes.mdx | 25 +++++ reference/lending-and-yield-commands.mdx | 55 +++++++++++ reference/market-commands.mdx | 76 +++++++++++++++ reference/meta-commands.mdx | 37 +++++++ 32 files changed, 1388 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 agents/overview.mdx create mode 100644 agents/reliability-patterns.mdx create mode 100644 agents/schema-driven.mdx create mode 100644 assets/docs-wordmark-dark.svg create mode 100644 assets/docs-wordmark-light.svg create mode 100644 concepts/config-and-cache.mdx create mode 100644 concepts/ids-and-amounts.mdx create mode 100644 concepts/output-contract.mdx create mode 100644 concepts/providers-and-auth.mdx create mode 100644 docs.json create mode 100644 guides/bridge.mdx create mode 100644 guides/examples-cookbook.mdx create mode 100644 guides/lending.mdx create mode 100644 guides/market-discovery.mdx create mode 100644 guides/swap.mdx create mode 100644 guides/yield.mdx create mode 100644 index.mdx create mode 100644 installation.mdx create mode 100644 quickstart.mdx create mode 100644 reference/bridge-and-swap-commands.mdx create mode 100644 reference/chain-aliases.mdx create mode 100644 reference/commands-overview.mdx create mode 100644 reference/envelope-schema.mdx create mode 100644 reference/exit-codes.mdx create mode 100644 reference/lending-and-yield-commands.mdx create mode 100644 reference/market-commands.mdx create mode 100644 reference/meta-commands.mdx diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..49bcca8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,35 @@ +name: docs + +on: + push: + paths: + - 'docs.json' + - '**/*.mdx' + - 'README.md' + - 'AGENTS.md' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs.json' + - '**/*.mdx' + - 'README.md' + - 'AGENTS.md' + - '.github/workflows/docs.yml' + workflow_dispatch: + +jobs: + mintlify-checks: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: '22' + + - name: Validate docs build + run: npx --yes mint validate + + - name: Check broken links + run: npx --yes mint broken-links diff --git a/.gitignore b/.gitignore index e606d38..df033da 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,9 @@ /bin/ /dist/ /defi +.mintlify/ *.test *.out .coverprofile .DS_Store -TODO.md \ No newline at end of file +TODO.md diff --git a/AGENTS.md b/AGENTS.md index 59f35d1..5a16f6e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,6 +52,8 @@ internal/ scripts/install.sh # macOS/Linux installer from GitHub Releases .goreleaser.yml # cross-platform release artifact config assets/ # static assets (logo, images) +docs.json # Mintlify docs site config +*.mdx + concepts/ guides/ ... # Mintlify docs content pages README.md # user-facing usage + caveats ``` @@ -78,6 +80,7 @@ README.md # user-facing usage + caveats - Amounts used for swaps/bridges are base units; keep both base and decimal forms consistent. - Release artifacts are built on `v*` tags via `.github/workflows/release.yml` and `.goreleaser.yml`. - `scripts/install.sh` installs the latest tagged release artifact into a writable user-space `PATH` directory by default (fallback `~/.local/bin`) and never uses sudo unless explicitly requested. +- Docs site local checks: `npx --yes mint validate` and `npx --yes mint broken-links` from repo root. ## Change patterns @@ -93,6 +96,10 @@ README.md # user-facing usage + caveats - Behavior changes: 1. keep cache keys deterministic 2. add runner-level tests for routing/fallback/strict mode +- Docs sync for user-facing changes: + 1. if adding a feature/command or changing behavior, update Mintlify docs + README + CHANGELOG + 2. if changing output schema/fields/exit codes, update contract/reference docs before merge + 3. if adding providers/chains/assets/aliases/key requirements, update provider/auth and examples docs ## Quality bar @@ -115,6 +122,6 @@ README.md # user-facing usage + caveats ## Maintenance note -- Keep `README.md`, `AGENTS.md`, and `CHANGELOG.md` aligned when commands, routing, caveats, or release-relevant behavior change. +- Keep `README.md`, `AGENTS.md`, `CHANGELOG.md`, and Mintlify docs (`docs.json` + `.mdx`) aligned when commands, routing, caveats, or release-relevant behavior change. Do not commit transient binaries like `./defi`. diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d089e0..cb988a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,7 +32,9 @@ Format: - Disabled Fibrous `monad` routing while Monad route responses are unstable. ### Docs -- None yet. +- Added a dedicated Mintlify documentation site (`docs.json` + structured MDX pages) with setup, guides, automation patterns, and command reference. +- Added a docs CI workflow that runs `mint validate` and `mint broken-links` on docs-related changes. +- Added an examples cookbook page with copy-paste workflows and clarified that API key requirements are provider-driven on specific routes. ### Security - None yet. diff --git a/README.md b/README.md index 5cf7400..aea047b 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,23 @@ Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP - **Chains & protocols** — browse top chains by TVL, inspect chain TVL by asset, discover protocols, resolve asset identifiers. - **Automation-friendly** — JSON-first output, field selection (`--select`), strict mode, and a machine-readable schema export. +## Documentation Site (Mintlify) + +This repo includes a dedicated Mintlify docs site (`docs.json` + `.mdx` pages at repo root). + +Preview locally: + +```bash +npx --yes mint dev --no-open +``` + +Validate before publishing: + +```bash +npx --yes mint validate +npx --yes mint broken-links +``` + ## Install ### 1) Quick install (macOS/Linux) diff --git a/agents/overview.mdx b/agents/overview.mdx new file mode 100644 index 0000000..809b586 --- /dev/null +++ b/agents/overview.mdx @@ -0,0 +1,41 @@ +--- +title: Agent Overview +description: Build robust agent workflows on top of deterministic CLI contracts. +--- + +## Why agents like defi-cli + +- Stable envelope schema (`version`, `success`, `error`, `meta`) +- Stable exit code mapping +- Canonical chain and asset IDs +- Deterministic `--select` projections +- Machine-readable command schema (`defi schema`) + +## Recommended request pattern + +1. Resolve all chain/asset inputs (`assets resolve` where useful). +2. Execute command with `--json --results-only` for success payloads. +3. Handle non-zero exit codes using `error.code` and `error.type`. +4. Persist canonical IDs and base-unit amounts. + +## Suggested defaults + +```bash +--timeout 12s --retries 2 --max-stale 5m +``` + +For strict workflows: + +```bash +--strict --no-stale +``` + +## Command allowlist mode + +Use `--enable-commands` to constrain executable commands in agent sandboxes. + +```bash +defi --enable-commands "providers list,yield opportunities" providers list --results-only +``` + +If a command is blocked, exit code `16` (`command_blocked`) is returned. diff --git a/agents/reliability-patterns.mdx b/agents/reliability-patterns.mdx new file mode 100644 index 0000000..9927d9a --- /dev/null +++ b/agents/reliability-patterns.mdx @@ -0,0 +1,36 @@ +--- +title: Reliability Patterns +description: Error handling, retries, stale policy, and strict-mode strategies for production agents. +--- + +## Error-first flow + +When command exit code is non-zero: + +1. Parse error envelope from stderr. +2. Branch on `error.code`. +3. Decide retry/fallback/abort. + +## Core retry and fallback guidance + +- Retry on `11` (`rate_limited`) and `12` (`provider_unavailable`) with backoff. +- Do not retry on `2` (`usage_error`) until input is corrected. +- Retry on `10` (`auth_error`) only after key provisioning. +- Treat `14` (`stale_data`) as SLO breach. + +## Cache/staleness strategy + +- Default cache mode is usually best for interactive and agent loops. +- Use `--no-stale` for strict freshness. +- Use `--max-stale` to control tolerated stale window on temporary provider failures. + +## Strict-mode strategy + +- Use `--strict` when partial provider aggregation is unacceptable. +- In strict mode, partial results fail with code `15`. + +## Suggested wrapper behavior + +- Always capture stdout and stderr separately. +- Treat stdout as success payload only when exit code is `0`. +- Persist `meta.request_id` for trace correlation. diff --git a/agents/schema-driven.mdx b/agents/schema-driven.mdx new file mode 100644 index 0000000..2b2ad15 --- /dev/null +++ b/agents/schema-driven.mdx @@ -0,0 +1,40 @@ +--- +title: Schema-Driven Integration +description: Use the machine-readable command schema to generate dynamic tooling. +--- + +## Fetch schema + +```bash +defi schema --results-only +``` + +Scope to a specific command path: + +```bash +defi schema "yield opportunities" --results-only +defi schema "bridge quote" --results-only +``` + +## Schema model + +Each node contains: + +- `path` +- `use` +- `short` +- `flags[]` (`name`, `type`, `usage`, `default`, optional `shorthand`) +- `subcommands[]` + +## Practical uses + +- Generate UI forms from flag metadata. +- Validate requested flags before execution. +- Produce autocomplete for command builders. +- Build policy-aware execution layers with `--enable-commands`. + +## Notes + +- Hidden commands are not included. +- Flag defaults are serialized as strings in schema output. +- Runtime constraints (for example, mutually exclusive amount flags) still require command execution validation. diff --git a/assets/docs-wordmark-dark.svg b/assets/docs-wordmark-dark.svg new file mode 100644 index 0000000..89da27d --- /dev/null +++ b/assets/docs-wordmark-dark.svg @@ -0,0 +1,3 @@ + + defi-cli + diff --git a/assets/docs-wordmark-light.svg b/assets/docs-wordmark-light.svg new file mode 100644 index 0000000..3494a11 --- /dev/null +++ b/assets/docs-wordmark-light.svg @@ -0,0 +1,3 @@ + + defi-cli + diff --git a/concepts/config-and-cache.mdx b/concepts/config-and-cache.mdx new file mode 100644 index 0000000..5ec3fa2 --- /dev/null +++ b/concepts/config-and-cache.mdx @@ -0,0 +1,60 @@ +--- +title: Config and Cache +description: Configure precedence, retries/timeouts, and stale fallback semantics. +--- + +## Config precedence + +`flags > env > config file > defaults` + +Default config path: + +```text +${XDG_CONFIG_HOME:-~/.config}/defi/config.yaml +``` + +Minimal config example: + +```yaml +output: json +strict: false +timeout: 10s +retries: 2 +cache: + enabled: true + max_stale: 5m +``` + +## Useful env vars + +| Variable | Purpose | +| --- | --- | +| `DEFI_OUTPUT` | `json` or `plain` | +| `DEFI_TIMEOUT` | Provider timeout | +| `DEFI_RETRIES` | Retries per request | +| `DEFI_MAX_STALE` | Stale fallback window | +| `DEFI_NO_STALE` | Disable stale fallback | +| `DEFI_NO_CACHE` | Disable cache | +| `DEFI_CACHE_PATH` | Cache DB path | +| `DEFI_CACHE_LOCK_PATH` | Cache lock path | + +## Cache behavior + +- Fresh cache hits (`age <= ttl`) return immediately. +- After TTL expires, CLI refetches providers. +- Stale data is served only when providers fail temporarily (`unavailable` or `rate_limited`) and within `max_stale`. +- If cache init fails (path/permissions), commands continue with cache disabled. +- Metadata commands (`version`, `schema`, `providers list`) bypass cache initialization. + +## Command TTLs + +| Command | TTL | +| --- | --- | +| `chains top`, `chains assets`, `protocols top`, `protocols categories` | `5m` | +| `lend markets`, `yield opportunities`, `bridge list`, `bridge details` | `60s` | +| `lend rates` | `30s` | +| `bridge quote`, `swap quote` | `15s` | + +## Strict mode + +If any selected provider fails and partial results occur, `--strict` returns exit code `15` (`partial_results`). diff --git a/concepts/ids-and-amounts.mdx b/concepts/ids-and-amounts.mdx new file mode 100644 index 0000000..ffcf2dc --- /dev/null +++ b/concepts/ids-and-amounts.mdx @@ -0,0 +1,51 @@ +--- +title: IDs and Amounts +description: Use canonical chain/asset IDs and normalized amount fields. +--- + +## Chain IDs + +`--chain`, `--from`, and `--to` accept: + +- CAIP-2: `eip155:1` +- Numeric EVM chain ID: `1` +- Alias: `ethereum`, `base`, `hyperevm`, `megaeth`, `gnosis`, `taiko`, etc. + +`defi-cli` normalizes these to canonical CAIP-2 IDs in output. + +## Asset IDs + +Asset inputs accept: + +- Symbol: `USDC` +- Token address: `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` +- CAIP-19: `eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` + +Output always returns canonical CAIP-19 in fields like `asset_id`, `from_asset_id`, `to_asset_id`. + +## Amount semantics + +For swap and bridge quotes: + +- `--amount` is base units (recommended for automation) +- `--amount-decimal` is human decimal form +- passing both returns a usage error + +Output includes both normalized forms: + +```json +"input_amount": { + "amount_base_units": "1000000", + "amount_decimal": "1", + "decimals": 6 +} +``` + +## Important caveats + +- Symbol parsing depends on the local bootstrap token registry. +- On chains without symbol coverage, pass address or CAIP-19 directly. +- For `lend` and `yield`, unresolved symbols skip DefiLlama symbol matching to avoid unsafe broad matches. +- MegaETH bootstrap symbol support currently includes `MEGA`, `WETH`, and `USDT` (`USDT` resolves to the chain `USDT0` contract). + +See [Chain Aliases](/reference/chain-aliases). diff --git a/concepts/output-contract.mdx b/concepts/output-contract.mdx new file mode 100644 index 0000000..fe63049 --- /dev/null +++ b/concepts/output-contract.mdx @@ -0,0 +1,66 @@ +--- +title: Output Contract +description: Understand the stable response envelope and rendering semantics. +--- + +`defi-cli` always emits a stable envelope in JSON mode unless `--results-only` is used on successful commands. + +## Success envelope + +```json +{ + "version": "v1", + "success": true, + "data": [...], + "error": null, + "warnings": [], + "meta": { + "request_id": "...", + "timestamp": "2026-02-24T03:00:10Z", + "command": "lend markets", + "providers": [{"name": "aave", "status": "ok", "latency_ms": 372}], + "cache": {"status": "miss", "age_ms": 0, "stale": false}, + "partial": false + } +} +``` + +## Error envelope behavior + +Errors always return the full envelope, even if you pass `--results-only` or `--select`. + +```json +{ + "version": "v1", + "success": false, + "data": [], + "error": { + "code": 10, + "type": "auth_error", + "message": "missing required API key for 1inch (DEFI_1INCH_API_KEY)" + }, + "meta": { + "command": "swap quote", + "cache": {"status": "bypass", "age_ms": 0, "stale": false}, + "partial": false + } +} +``` + +## Rendering flags + +| Flag | Behavior | +| --- | --- | +| `--json` | JSON output (default) | +| `--plain` | key=value lines | +| `--results-only` | output only `data` on success | +| `--select a,b,c` | project selected fields from `data` | + +## Stability guarantees + +- `error.code` maps to stable process exit codes +- `meta.command` uses normalized command paths +- provider status values are stable (`ok`, `auth_error`, `rate_limited`, `unavailable`, `error`) +- APY values are percentage points (`2.3` means `2.3%`) + +See [Envelope Schema](/reference/envelope-schema) and [Exit Codes](/reference/exit-codes). diff --git a/concepts/providers-and-auth.mdx b/concepts/providers-and-auth.mdx new file mode 100644 index 0000000..e43c897 --- /dev/null +++ b/concepts/providers-and-auth.mdx @@ -0,0 +1,45 @@ +--- +title: Providers and Auth +description: Provider coverage, key requirements, and routing behavior. +--- + +## Provider matrix + +| Provider | Capabilities | Key required | +| --- | --- | --- | +| `defillama` | chains/protocols/lend/yield + bridge analytics | Route-specific | +| `aave` | lend, yield | No | +| `morpho` | lend, yield | No | +| `across` | bridge quote | No | +| `lifi` | bridge quote | No | +| `bungee` | bridge quote, swap quote | No (default mode) | +| `1inch` | swap quote | Yes | +| `uniswap` | swap quote | Yes | +| `fibrous` | swap quote | No | + +API keys in `defi-cli` are provider constraints, not CLI monetization/auth. If a provider endpoint requires credentials, the corresponding command requires that provider key. + +## Key requirements by route + +- `swap quote --provider 1inch` -> `DEFI_1INCH_API_KEY` +- `swap quote --provider uniswap` -> `DEFI_UNISWAP_API_KEY` +- `chains assets`, `bridge list`, `bridge details` -> `DEFI_DEFILLAMA_API_KEY` + +Optional Bungee dedicated backend mode requires: + +- `DEFI_BUNGEE_API_KEY` +- `DEFI_BUNGEE_AFFILIATE` + +If either is missing, bungee quotes use public backend. + +## Routing and fallback + +- Lending routes by `--protocol` (`aave`, `morpho`, `spark`). +- Direct provider routes may fallback to DefiLlama on selected failures. +- Fallback is skipped when asset symbol resolution is unsafe. + +## Data caveats + +- Morpho can surface very high APY in tiny markets. Use `--min-tvl-usd`. +- Bungee quote support is chain + token dependent. +- Fibrous currently supports `base`, `hyperevm`, and `citrea` (`monad` temporarily disabled). diff --git a/docs.json b/docs.json new file mode 100644 index 0000000..cba5bae --- /dev/null +++ b/docs.json @@ -0,0 +1,119 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "defi-cli", + "description": "Agent-first DeFi retrieval CLI documentation", + "colors": { + "primary": "#0F766E", + "light": "#14B8A6", + "dark": "#0F766E" + }, + "favicon": "/assets/logo.png", + "logo": { + "light": "/assets/docs-wordmark-light.svg", + "dark": "/assets/docs-wordmark-dark.svg" + }, + "navigation": { + "tabs": [ + { + "tab": "Learn", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "index", + "installation", + "quickstart" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "concepts/output-contract", + "concepts/ids-and-amounts", + "concepts/config-and-cache", + "concepts/providers-and-auth" + ] + }, + { + "group": "Workflow Guides", + "pages": [ + "guides/examples-cookbook", + "guides/market-discovery", + "guides/lending", + "guides/yield", + "guides/bridge", + "guides/swap" + ] + } + ] + }, + { + "tab": "Agents", + "groups": [ + { + "group": "Automation", + "pages": [ + "agents/overview", + "agents/schema-driven", + "agents/reliability-patterns" + ] + } + ] + }, + { + "tab": "Reference", + "groups": [ + { + "group": "CLI Commands", + "pages": [ + "reference/commands-overview", + "reference/market-commands", + "reference/lending-and-yield-commands", + "reference/bridge-and-swap-commands", + "reference/meta-commands" + ] + }, + { + "group": "Contracts", + "pages": [ + "reference/envelope-schema", + "reference/exit-codes", + "reference/chain-aliases" + ] + } + ] + } + ] + }, + "navbar": { + "links": [ + { + "label": "GitHub", + "href": "https://github.com/ggonzalez94/defi-cli" + } + ], + "primary": { + "type": "button", + "label": "Install", + "href": "https://github.com/ggonzalez94/defi-cli#install" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "mcp", + "cursor", + "vscode" + ] + }, + "footer": { + "socials": { + "github": "https://github.com/ggonzalez94/defi-cli" + } + } +} diff --git a/guides/bridge.mdx b/guides/bridge.mdx new file mode 100644 index 0000000..3f13ef3 --- /dev/null +++ b/guides/bridge.mdx @@ -0,0 +1,41 @@ +--- +title: Bridge +description: Get bridge quotes and bridge analytics with provider-specific behavior. +--- + +## Quote routes + +Default provider is `across`: + +```bash +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +``` + +Use a specific provider: + +```bash +defi bridge quote --provider lifi --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +defi bridge quote --provider bungee --from hyperevm --to 8453 --asset USDC --amount 5000000 --results-only +``` + +Amount inputs: + +```bash +defi bridge quote --from 1 --to 8453 --asset USDC --amount-decimal 1.5 --results-only +``` + +## Bridge analytics + +These commands require `DEFI_DEFILLAMA_API_KEY`: + +```bash +defi bridge list --limit 20 --results-only +defi bridge details --bridge layerzero --results-only +``` + +## Notes + +- `--to-asset` is optional; default is source symbol on destination chain. +- Bungee quote mode is keyless by default. +- Optional bungee dedicated backend mode requires both `DEFI_BUNGEE_API_KEY` and `DEFI_BUNGEE_AFFILIATE`. +- Bungee quote requests use deterministic placeholder sender/receiver addresses for quote-only flows. diff --git a/guides/examples-cookbook.mdx b/guides/examples-cookbook.mdx new file mode 100644 index 0000000..5da0e8b --- /dev/null +++ b/guides/examples-cookbook.mdx @@ -0,0 +1,73 @@ +--- +title: Examples Cookbook +description: High-signal copy-paste examples for common human and agent workflows. +--- + +These examples are intentionally concise and automation-friendly. + +## Market scan in one minute + +```bash +defi chains top --limit 10 --results-only --select rank,chain,chain_id,tvl_usd +defi protocols top --category lending --limit 10 --results-only +``` + +## Resolve canonical IDs before storing plans + +```bash +defi assets resolve --chain base --asset USDC --results-only +defi assets resolve --chain hyperevm --asset WHYPE --results-only +``` + +## Safe yield ranking for production filters + +```bash +defi yield opportunities \ + --chain 1 \ + --asset USDC \ + --providers aave,morpho \ + --min-tvl-usd 1000000 \ + --max-risk medium \ + --sort score \ + --limit 20 \ + --results-only +``` + +## Bridge quote with base units + +```bash +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +``` + +## Swap quote with decimal amount + +```bash +defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount-decimal 2.5 --results-only +``` + +## Schema-driven command discovery + +```bash +defi schema --results-only +defi schema "swap quote" --results-only +``` + +## Strict mode for no-partial workflows + +```bash +defi yield opportunities --chain 1 --asset USDC --strict --results-only +``` + +## Policy-constrained execution for agents + +```bash +defi --enable-commands "providers list,yield opportunities" providers list --results-only +``` + +## API key failure example (provider-gated route) + +```bash +defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only +``` + +If `DEFI_1INCH_API_KEY` is missing, the command fails with exit code `10` (`auth_error`) because `1inch` requires provider credentials. diff --git a/guides/lending.mdx b/guides/lending.mdx new file mode 100644 index 0000000..bf19aa2 --- /dev/null +++ b/guides/lending.mdx @@ -0,0 +1,41 @@ +--- +title: Lending +description: Query lending markets and rates across Aave, Morpho, and Spark routing. +--- + +## Markets + +```bash +defi lend markets --protocol aave --chain 1 --asset USDC --limit 10 --results-only +``` + +## Rates + +```bash +defi lend rates --protocol morpho --chain 1 --asset USDC --limit 10 --results-only +``` + +## Protocol routing + +- `--protocol aave` -> Aave adapter +- `--protocol morpho` -> Morpho adapter +- `--protocol spark` -> DefiLlama route + +For direct adapters, fallback to DefiLlama can occur on selected failures (`unavailable`, `unsupported`, `rate_limited`) when symbol resolution is safe. + +## Suggested filters and reliability defaults + +```bash +defi lend rates --protocol morpho --chain 1 --asset USDC --limit 20 --timeout 12s --retries 2 --max-stale 5m --results-only +``` + +## Output fields + +`lend markets` returns: + +- `protocol`, `chain_id`, `asset_id` +- `supply_apy`, `borrow_apy` +- `tvl_usd`, `liquidity_usd` +- `source_url`, `fetched_at` + +`lend rates` adds `utilization`. diff --git a/guides/market-discovery.mdx b/guides/market-discovery.mdx new file mode 100644 index 0000000..9170124 --- /dev/null +++ b/guides/market-discovery.mdx @@ -0,0 +1,43 @@ +--- +title: Market Discovery +description: Discover chains, protocols, and assets before running strategy-specific commands. +--- + +Use market-discovery commands to scope chains/protocols and normalize assets first. + +## Top chains by TVL + +```bash +defi chains top --limit 10 --results-only --select rank,chain,chain_id,tvl_usd +``` + +## Asset TVL on a chain + +```bash +export DEFI_DEFILLAMA_API_KEY=... +defi chains assets --chain 1 --asset USDC --limit 20 --results-only +``` + +Notes: + +- `chains assets` requires `DEFI_DEFILLAMA_API_KEY`. +- If filtering by token address/CAIP-19, the token must have a known symbol on that chain. + +## Top protocols and categories + +```bash +defi protocols top --limit 20 --results-only +defi protocols top --category lending --limit 20 --results-only +defi protocols categories --results-only +``` + +Category ranking is deterministic: `tvl_usd`, then protocol count, then name. + +## Resolve assets to canonical IDs + +```bash +defi assets resolve --chain base --asset USDC --results-only +defi assets resolve --chain eip155:1 --asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --results-only +``` + +Use this as a normalization step before storing request plans for agents. diff --git a/guides/swap.mdx b/guides/swap.mdx new file mode 100644 index 0000000..2d98338 --- /dev/null +++ b/guides/swap.mdx @@ -0,0 +1,36 @@ +--- +title: Swap +description: Get swap quotes across 1inch, Uniswap, Fibrous, and Bungee. +--- + +## 1inch (key required) + +```bash +export DEFI_1INCH_API_KEY=... +defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only +``` + +## Uniswap (key required) + +```bash +export DEFI_UNISWAP_API_KEY=... +defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only +``` + +## Fibrous (keyless) + +```bash +defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only +``` + +## Bungee Auto (keyless default) + +```bash +defi swap quote --provider bungee --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 5000000 --results-only +``` + +## Notes + +- `--amount` and `--amount-decimal` are mutually exclusive. +- Output always includes normalized `input_amount` and `estimated_out` with base and decimal forms. +- Fibrous currently supports `base`, `hyperevm`, and `citrea`. diff --git a/guides/yield.mdx b/guides/yield.mdx new file mode 100644 index 0000000..b7def8c --- /dev/null +++ b/guides/yield.mdx @@ -0,0 +1,47 @@ +--- +title: Yield +description: Rank and filter yield opportunities with provider-aware behavior. +--- + +## Basic ranking + +```bash +defi yield opportunities --chain 1 --asset USDC --limit 20 --results-only +``` + +## Select providers explicitly + +```bash +defi yield opportunities --chain 1 --asset USDC --providers defillama,aave,morpho --limit 20 --results-only +``` + +`--providers` expects provider names from `defi providers list`. + +## Control risk and quality + +```bash +defi yield opportunities \ + --chain 1 \ + --asset USDC \ + --providers aave,morpho \ + --min-tvl-usd 1000000 \ + --min-apy 1 \ + --max-risk medium \ + --sort score \ + --limit 20 \ + --results-only +``` + +## Incomplete opportunities + +```bash +defi yield opportunities --chain 1 --asset USDC --include-incomplete --results-only +``` + +When enabled, warnings may indicate missing APY/TVL and combined-provider counts. + +## Important caveats + +- APY values are percentage points (`2.3` = `2.3%`). +- Morpho may produce extreme APY for very small markets; use `--min-tvl-usd`. +- If an asset symbol cannot be resolved safely, DefiLlama may be skipped. diff --git a/index.mdx b/index.mdx new file mode 100644 index 0000000..66c7afb --- /dev/null +++ b/index.mdx @@ -0,0 +1,62 @@ +--- +title: defi-cli Docs +description: Query DeFi lending, yield, bridge, and swap data from a single agent-first CLI. +--- + +`defi-cli` is an agent-first DeFi retrieval CLI with a stable automation contract: + +- Stable JSON envelope + deterministic field naming +- Stable exit codes +- Canonical chain and asset IDs (CAIP-2 / CAIP-19) +- Canonical amount handling (base units + decimal normalization) + +## Start here + +- New user: [Installation](/installation) -> [Quickstart](/quickstart) +- Building automation: [Output Contract](/concepts/output-contract) -> [Agent Overview](/agents/overview) +- Need exact command flags: [Command Reference](/reference/commands-overview) +- Want copy-paste scenarios: [Examples Cookbook](/guides/examples-cookbook) + +## Example + +```bash +defi providers list --results-only +``` + +```json +[ + { + "name": "defillama", + "type": "market+yields", + "requires_key": false, + "capabilities": ["chains.top", "chains.assets", "protocols.top", "protocols.categories", "lend.markets", "lend.rates", "yield.opportunities", "bridge.list", "bridge.details"], + "key_env_var": "DEFI_DEFILLAMA_API_KEY" + }, + { + "name": "aave", + "type": "lending+yield", + "requires_key": false, + "capabilities": ["lend.markets", "lend.rates", "yield.opportunities"] + } +] +``` + +## Key-gated routes + +Most commands are keyless. These routes require keys because the upstream providers require authentication: + +| Route | Env var | +| --- | --- | +| `swap quote --provider 1inch` | `DEFI_1INCH_API_KEY` | +| `swap quote --provider uniswap` | `DEFI_UNISWAP_API_KEY` | +| `chains assets` | `DEFI_DEFILLAMA_API_KEY` | +| `bridge list` | `DEFI_DEFILLAMA_API_KEY` | +| `bridge details` | `DEFI_DEFILLAMA_API_KEY` | + +Bungee quotes are keyless by default. Dedicated backend mode requires both `DEFI_BUNGEE_API_KEY` and `DEFI_BUNGEE_AFFILIATE`. + +## Next + +- [Quickstart](/quickstart) +- [Providers and Auth](/concepts/providers-and-auth) +- [Examples Cookbook](/guides/examples-cookbook) diff --git a/installation.mdx b/installation.mdx new file mode 100644 index 0000000..2a762be --- /dev/null +++ b/installation.mdx @@ -0,0 +1,59 @@ +--- +title: Installation +description: Install defi-cli from release artifacts, Go, or source. +--- + +## Quick install (macOS/Linux) + +```bash +curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh +``` + +Install a specific version: + +```bash +curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh -s -- v0.2.0 +``` + +## Go install + +```bash +go install github.com/ggonzalez94/defi-cli/cmd/defi@latest +``` + +## Build from source + +```bash +git clone https://github.com/ggonzalez94/defi-cli.git +cd defi-cli +go build -o defi ./cmd/defi +``` + +## Verify install + +```bash +defi version --long +defi --help +``` + +## Optional shell completion + +```bash +defi completion zsh > ~/.zsh/completions/_defi +defi completion bash > ~/.local/share/bash-completion/completions/defi +defi completion fish > ~/.config/fish/completions/defi.fish +``` + +## API key setup + +Use environment variables (recommended): + +```bash +export DEFI_1INCH_API_KEY=... +export DEFI_UNISWAP_API_KEY=... +export DEFI_DEFILLAMA_API_KEY=... +export DEFI_BUNGEE_API_KEY=... +export DEFI_BUNGEE_AFFILIATE=... +``` + +Most routes do not require keys. See [Providers and Auth](/concepts/providers-and-auth) for route-level requirements. diff --git a/quickstart.mdx b/quickstart.mdx new file mode 100644 index 0000000..7a1dafe --- /dev/null +++ b/quickstart.mdx @@ -0,0 +1,65 @@ +--- +title: Quickstart +description: Run the most common defi-cli workflows in a few minutes. +--- + +## 1. List providers + +```bash +defi providers list --results-only +``` + +## 2. Discover market context + +```bash +defi chains top --limit 10 --results-only --select rank,chain,chain_id,tvl_usd +defi protocols top --category lending --limit 10 --results-only +``` + +## 3. Resolve an asset to canonical ID + +```bash +defi assets resolve --chain base --asset USDC --results-only +``` + +## 4. Query lending markets and rates + +```bash +defi lend markets --protocol aave --chain 1 --asset USDC --limit 5 --results-only +defi lend rates --protocol morpho --chain 1 --asset USDC --limit 5 --results-only +``` + +## 5. Rank yield opportunities + +```bash +defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --limit 10 --results-only +defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --min-tvl-usd 1000000 --limit 10 --results-only +``` + +`--providers` expects provider names from `providers list` (`defillama,aave,morpho`), not protocol categories. + +## 6. Get bridge and swap quotes + +```bash +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +defi bridge quote --provider bungee --from hyperevm --to 8453 --asset USDC --amount 1000000 --results-only + +defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only +``` + +## 7. Use schema for machine integration + +```bash +defi schema --results-only +defi schema "yield opportunities" --results-only +``` + +## 8. Add reliability defaults + +```bash +defi yield opportunities --chain 1 --asset USDC --timeout 12s --retries 2 --max-stale 5m --results-only +``` + +For more copy-paste scenarios, see [Examples Cookbook](/guides/examples-cookbook). + +Next: [Output Contract](/concepts/output-contract) diff --git a/reference/bridge-and-swap-commands.mdx b/reference/bridge-and-swap-commands.mdx new file mode 100644 index 0000000..60403e3 --- /dev/null +++ b/reference/bridge-and-swap-commands.mdx @@ -0,0 +1,71 @@ +--- +title: Bridge and Swap Commands +description: Full reference for quote and bridge-analytics command families. +--- + +## `bridge quote` + +```bash +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +``` + +Flags: + +- `--provider string` (`across|lifi|bungee`, default `across`) +- `--from string` required +- `--to string` required +- `--asset string` required +- `--to-asset string` optional +- `--amount string` or `--amount-decimal string` + +## `bridge list` + +```bash +defi bridge list --limit 20 --include-chains --results-only +``` + +Flags: + +- `--limit int` (default `20`) +- `--include-chains` bool (default `true`) + +Auth: requires `DEFI_DEFILLAMA_API_KEY`. + +Reason: this route uses DefiLlama bridge analytics endpoints that are provider-gated. + +## `bridge details` + +```bash +defi bridge details --bridge layerzero --include-chain-breakdown --results-only +``` + +Flags: + +- `--bridge string` required +- `--include-chain-breakdown` bool (default `true`) + +Auth: requires `DEFI_DEFILLAMA_API_KEY`. + +Reason: this route uses DefiLlama bridge analytics endpoints that are provider-gated. + +## `swap quote` + +```bash +defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only +``` + +Flags: + +- `--provider string` (`1inch|uniswap|fibrous|bungee`, default `1inch`) +- `--chain string` required +- `--from-asset string` required +- `--to-asset string` required +- `--amount string` or `--amount-decimal string` + +Auth requirements: + +- `1inch` -> `DEFI_1INCH_API_KEY` +- `uniswap` -> `DEFI_UNISWAP_API_KEY` +- `fibrous`, `bungee` -> keyless by default + +These requirements are driven by provider APIs. `defi-cli` passes through provider auth requirements per route/provider pair. diff --git a/reference/chain-aliases.mdx b/reference/chain-aliases.mdx new file mode 100644 index 0000000..ce8be1e --- /dev/null +++ b/reference/chain-aliases.mdx @@ -0,0 +1,36 @@ +--- +title: Chain Aliases +description: Supported chain alias normalization for chain-related flags. +--- + +`--chain`, `--from`, and `--to` normalize aliases, numeric IDs, and CAIP-2 values. + +## Common aliases + +| Canonical chain ID | Example aliases | +| --- | --- | +| `eip155:1` | `ethereum`, `mainnet`, `1` | +| `eip155:10` | `optimism`, `op mainnet`, `10` | +| `eip155:56` | `bsc`, `56` | +| `eip155:100` | `gnosis`, `xdai`, `100` | +| `eip155:137` | `polygon`, `137` | +| `eip155:8453` | `base`, `8453` | +| `eip155:42161` | `arbitrum`, `42161` | +| `eip155:43114` | `avalanche`, `43114` | +| `eip155:5000` | `mantle`, `5000` | +| `eip155:4326` | `megaeth`, `mega eth`, `mega-eth`, `4326` | +| `eip155:57073` | `ink`, `57073` | +| `eip155:534352` | `scroll`, `534352` | +| `eip155:80094` | `berachain`, `80094` | +| `eip155:81457` | `blast`, `81457` | +| `eip155:252` | `fraxtal`, `252` | +| `eip155:480` | `worldchain`, `world chain`, `world-chain`, `480` | +| `eip155:42220` | `celo`, `42220` | +| `eip155:167000` | `taiko`, `taiko alethia`, `taiko-alethia`, `167000` | +| `eip155:324` | `zksync`, `zksync era`, `zksync-era`, `324` | +| `eip155:999` | `hyperevm`, `hyper evm`, `hyper-evm`, `999` | +| `eip155:143` | `monad`, `143` | +| `eip155:4114` | `citrea`, `4114` | +| `eip155:146` | `sonic`, `146` | + +If a numeric EVM chain ID is unknown, `defi-cli` still normalizes it to `eip155:`. diff --git a/reference/commands-overview.mdx b/reference/commands-overview.mdx new file mode 100644 index 0000000..517a8d1 --- /dev/null +++ b/reference/commands-overview.mdx @@ -0,0 +1,48 @@ +--- +title: Commands Overview +description: Top-level command map and shared global flags. +--- + +## Top-level commands + +- `assets` +- `bridge` +- `chains` +- `lend` +- `protocols` +- `providers` +- `schema` +- `swap` +- `version` +- `yield` +- `completion` + +## Global flags + +| Flag | Type | Description | +| --- | --- | --- | +| `--json` | bool | Output JSON (default) | +| `--plain` | bool | Output plain text | +| `--results-only` | bool | Output only data payload on success | +| `--select` | string | Select fields from payload | +| `--strict` | bool | Fail on partial results | +| `--timeout` | duration string | Provider request timeout | +| `--retries` | int | Retries per provider request | +| `--max-stale` | duration string | Max stale fallback window | +| `--no-stale` | bool | Disable stale fallback | +| `--no-cache` | bool | Disable cache reads/writes | +| `--enable-commands` | CSV string | Command allowlist policy | +| `--config` | string | Config file path | + +## Usage pattern + +```bash +defi [flags] [global flags] +``` + +Examples: + +```bash +defi lend markets --protocol aave --chain 1 --asset USDC --results-only +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --timeout 12s --retries 2 --results-only +``` diff --git a/reference/envelope-schema.mdx b/reference/envelope-schema.mdx new file mode 100644 index 0000000..0657fc2 --- /dev/null +++ b/reference/envelope-schema.mdx @@ -0,0 +1,44 @@ +--- +title: Envelope Schema +description: Field-level contract for success and error responses. +--- + +## Envelope fields + +| Field | Type | Notes | +| --- | --- | --- | +| `version` | string | Envelope version (`v1`) | +| `success` | bool | `true` on success, `false` on error | +| `data` | any | Command payload (array/object depending on command) | +| `error` | object or `null` | Present on failures | +| `warnings` | string[] | Optional warnings | +| `meta` | object | Execution metadata | + +## `meta` + +| Field | Type | Notes | +| --- | --- | --- | +| `request_id` | string | Unique per invocation | +| `timestamp` | RFC3339 timestamp | UTC | +| `command` | string | Normalized command path | +| `providers` | array | Provider statuses and latencies | +| `cache` | object | Cache status metadata | +| `partial` | bool | Indicates partial aggregation | + +## `cache` + +| Field | Type | Values | +| --- | --- | --- | +| `status` | string | `bypass`, `miss`, `hit`, `write` | +| `age_ms` | int | Age of cached response in milliseconds | +| `stale` | bool | Whether served cache entry is stale | + +## Key payload models + +- Market commands: `ChainTVL`, `ChainAssetTVL`, `ProtocolTVL`, `ProtocolCategory`, `AssetResolution` +- Lending: `LendMarket`, `LendRate` +- Yield: `YieldOpportunity` +- Bridge: `BridgeQuote`, `BridgeSummary`, `BridgeDetails` +- Swap: `SwapQuote` + +For practical examples, see [Quickstart](/quickstart). diff --git a/reference/exit-codes.mdx b/reference/exit-codes.mdx new file mode 100644 index 0000000..dbc16d5 --- /dev/null +++ b/reference/exit-codes.mdx @@ -0,0 +1,25 @@ +--- +title: Exit Codes +description: Stable exit code contract for scripts and agents. +--- + +## Stable mapping + +| Exit code | Type | Meaning | +| --- | --- | --- | +| `0` | success | Command succeeded | +| `1` | internal_error | Internal execution error | +| `2` | usage_error | Invalid command or flags | +| `10` | auth_error | Missing/invalid provider key | +| `11` | rate_limited | Provider throttling | +| `12` | provider_unavailable | Provider unavailable | +| `13` | unsupported | Unsupported input/provider pair | +| `14` | stale_data | Stale data beyond configured budget | +| `15` | partial_results | Partial results with `--strict` | +| `16` | command_blocked | Blocked by `--enable-commands` policy | + +## Error handling recommendation + +- Parse stderr envelope on non-zero exits. +- Branch logic on `error.code`. +- Use retries only for transient types (`11`, `12`). diff --git a/reference/lending-and-yield-commands.mdx b/reference/lending-and-yield-commands.mdx new file mode 100644 index 0000000..ac69d52 --- /dev/null +++ b/reference/lending-and-yield-commands.mdx @@ -0,0 +1,55 @@ +--- +title: Lending and Yield Commands +description: Full reference for lend and yield command flags and examples. +--- + +## `lend markets` + +```bash +defi lend markets --protocol aave --chain 1 --asset USDC --limit 20 --results-only +``` + +Flags: + +- `--protocol string` (`aave`, `morpho`, `spark`) required +- `--chain string` required +- `--asset string` required +- `--limit int` (default `20`) + +## `lend rates` + +```bash +defi lend rates --protocol morpho --chain 1 --asset USDC --limit 20 --results-only +``` + +Flags are the same as `lend markets`. + +## `yield opportunities` + +```bash +defi yield opportunities \ + --chain 1 \ + --asset USDC \ + --providers aave,morpho \ + --min-tvl-usd 1000000 \ + --max-risk medium \ + --sort score \ + --limit 20 \ + --results-only +``` + +Flags: + +- `--chain string` required +- `--asset string` required +- `--limit int` (default `20`) +- `--min-tvl-usd float` (default `0`) +- `--min-apy float` (default `0`) +- `--max-risk string` (`low|medium|high|unknown`, default `high`) +- `--providers string` (`defillama,aave,morpho`) +- `--sort string` (`score|apy_total|tvl_usd|liquidity_usd`, default `score`) +- `--include-incomplete` bool (default `false`) + +## Provider-selection note + +`--providers` accepts provider names, not protocol categories. diff --git a/reference/market-commands.mdx b/reference/market-commands.mdx new file mode 100644 index 0000000..55e4df8 --- /dev/null +++ b/reference/market-commands.mdx @@ -0,0 +1,76 @@ +--- +title: Market Commands +description: Reference for providers, chains, protocols, and assets commands. +--- + +## `providers list` + +List supported providers and capability auth metadata. + +```bash +defi providers list --results-only +``` + +## `chains top` + +Top chains by TVL. + +```bash +defi chains top --limit 20 --results-only +``` + +Flags: + +- `--limit int` (default `20`) + +## `chains assets` + +Asset-level TVL for a chain. + +```bash +defi chains assets --chain 1 --asset USDC --limit 20 --results-only +``` + +Flags: + +- `--chain string` (required) +- `--asset string` (optional filter) +- `--limit int` (default `20`) + +Auth: requires `DEFI_DEFILLAMA_API_KEY`. + +Reason: `chains assets` is backed by a DefiLlama endpoint that is provider-gated. + +## `protocols top` + +Top protocols by TVL. + +```bash +defi protocols top --category lending --limit 20 --results-only +``` + +Flags: + +- `--category string` (optional) +- `--limit int` (default `20`) + +## `protocols categories` + +List categories with protocol counts and TVL. + +```bash +defi protocols categories --results-only +``` + +## `assets resolve` + +Resolve symbol/address/CAIP-19 to canonical asset metadata. + +```bash +defi assets resolve --chain base --asset USDC --results-only +``` + +Flags: + +- `--chain string` (required) +- `--asset string` or `--symbol string` (at least one required) diff --git a/reference/meta-commands.mdx b/reference/meta-commands.mdx new file mode 100644 index 0000000..fbab59b --- /dev/null +++ b/reference/meta-commands.mdx @@ -0,0 +1,37 @@ +--- +title: Meta Commands +description: Schema, version, and completion command reference. +--- + +## `schema [command path]` + +Print machine-readable command schema. + +```bash +defi schema --results-only +defi schema "swap quote" --results-only +``` + +## `version` + +Print CLI version. + +```bash +defi version +defi version --long +``` + +## `completion` + +Generate shell completion scripts. + +```bash +defi completion zsh +defi completion bash +defi completion fish +defi completion powershell +``` + +## Cache bypass behavior + +`version`, `schema`, and `providers list` bypass cache initialization. From 0b9857798a95b8a80d4177284e32281eed66767c Mon Sep 17 00:00:00 2001 From: Gustavo Gonzalez Date: Tue, 24 Feb 2026 15:21:03 -0400 Subject: [PATCH 2/5] docs: use lobster header logo and remove overlapping cookbook --- CHANGELOG.md | 2 +- assets/docs-lobster.png | Bin 0 -> 4702 bytes assets/docs-logo-lobster-dark.png | Bin 0 -> 6404 bytes assets/docs-logo-lobster-light.png | Bin 0 -> 6423 bytes assets/docs-wordmark-dark.svg | 3 -- assets/docs-wordmark-light.svg | 3 -- docs.json | 7 ++- guides/examples-cookbook.mdx | 73 ----------------------------- index.mdx | 2 - quickstart.mdx | 2 - 10 files changed, 4 insertions(+), 88 deletions(-) create mode 100644 assets/docs-lobster.png create mode 100644 assets/docs-logo-lobster-dark.png create mode 100644 assets/docs-logo-lobster-light.png delete mode 100644 assets/docs-wordmark-dark.svg delete mode 100644 assets/docs-wordmark-light.svg delete mode 100644 guides/examples-cookbook.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index cb988a0..f3acbe6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,7 +34,7 @@ Format: ### Docs - Added a dedicated Mintlify documentation site (`docs.json` + structured MDX pages) with setup, guides, automation patterns, and command reference. - Added a docs CI workflow that runs `mint validate` and `mint broken-links` on docs-related changes. -- Added an examples cookbook page with copy-paste workflows and clarified that API key requirements are provider-driven on specific routes. +- Refined docs IA by removing overlapping cookbook content, clarifying provider-driven API key requirements, and updating header branding with a lobster wordmark logo. ### Security - None yet. diff --git a/assets/docs-lobster.png b/assets/docs-lobster.png new file mode 100644 index 0000000000000000000000000000000000000000..346b6ffed93944638a76771bc17732764d27255c GIT binary patch literal 4702 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 literal 0 HcmV?d00001 diff --git a/assets/docs-logo-lobster-dark.png b/assets/docs-logo-lobster-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..9e57f3be9b9e1e2898471dbd51d7e1a77873e3fb GIT binary patch literal 6404 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 literal 0 HcmV?d00001 diff --git a/assets/docs-logo-lobster-light.png b/assets/docs-logo-lobster-light.png new file mode 100644 index 0000000000000000000000000000000000000000..c58496696db23bb56d4a3ac57bd7113f34a44230 GIT binary patch literal 6423 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 lq)C$|O`0@m(gd@O{{fzi;AmxFa - defi-cli - diff --git a/assets/docs-wordmark-light.svg b/assets/docs-wordmark-light.svg deleted file mode 100644 index 3494a11..0000000 --- a/assets/docs-wordmark-light.svg +++ /dev/null @@ -1,3 +0,0 @@ - - defi-cli - diff --git a/docs.json b/docs.json index cba5bae..8a60479 100644 --- a/docs.json +++ b/docs.json @@ -8,10 +8,10 @@ "light": "#14B8A6", "dark": "#0F766E" }, - "favicon": "/assets/logo.png", + "favicon": "/assets/docs-lobster.png", "logo": { - "light": "/assets/docs-wordmark-light.svg", - "dark": "/assets/docs-wordmark-dark.svg" + "light": "/assets/docs-logo-lobster-light.png", + "dark": "/assets/docs-logo-lobster-dark.png" }, "navigation": { "tabs": [ @@ -38,7 +38,6 @@ { "group": "Workflow Guides", "pages": [ - "guides/examples-cookbook", "guides/market-discovery", "guides/lending", "guides/yield", diff --git a/guides/examples-cookbook.mdx b/guides/examples-cookbook.mdx deleted file mode 100644 index 5da0e8b..0000000 --- a/guides/examples-cookbook.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Examples Cookbook -description: High-signal copy-paste examples for common human and agent workflows. ---- - -These examples are intentionally concise and automation-friendly. - -## Market scan in one minute - -```bash -defi chains top --limit 10 --results-only --select rank,chain,chain_id,tvl_usd -defi protocols top --category lending --limit 10 --results-only -``` - -## Resolve canonical IDs before storing plans - -```bash -defi assets resolve --chain base --asset USDC --results-only -defi assets resolve --chain hyperevm --asset WHYPE --results-only -``` - -## Safe yield ranking for production filters - -```bash -defi yield opportunities \ - --chain 1 \ - --asset USDC \ - --providers aave,morpho \ - --min-tvl-usd 1000000 \ - --max-risk medium \ - --sort score \ - --limit 20 \ - --results-only -``` - -## Bridge quote with base units - -```bash -defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only -``` - -## Swap quote with decimal amount - -```bash -defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount-decimal 2.5 --results-only -``` - -## Schema-driven command discovery - -```bash -defi schema --results-only -defi schema "swap quote" --results-only -``` - -## Strict mode for no-partial workflows - -```bash -defi yield opportunities --chain 1 --asset USDC --strict --results-only -``` - -## Policy-constrained execution for agents - -```bash -defi --enable-commands "providers list,yield opportunities" providers list --results-only -``` - -## API key failure example (provider-gated route) - -```bash -defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only -``` - -If `DEFI_1INCH_API_KEY` is missing, the command fails with exit code `10` (`auth_error`) because `1inch` requires provider credentials. diff --git a/index.mdx b/index.mdx index 66c7afb..e3a91a3 100644 --- a/index.mdx +++ b/index.mdx @@ -15,7 +15,6 @@ description: Query DeFi lending, yield, bridge, and swap data from a single agen - New user: [Installation](/installation) -> [Quickstart](/quickstart) - Building automation: [Output Contract](/concepts/output-contract) -> [Agent Overview](/agents/overview) - Need exact command flags: [Command Reference](/reference/commands-overview) -- Want copy-paste scenarios: [Examples Cookbook](/guides/examples-cookbook) ## Example @@ -59,4 +58,3 @@ Bungee quotes are keyless by default. Dedicated backend mode requires both `DEFI - [Quickstart](/quickstart) - [Providers and Auth](/concepts/providers-and-auth) -- [Examples Cookbook](/guides/examples-cookbook) diff --git a/quickstart.mdx b/quickstart.mdx index 7a1dafe..7bf574f 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -60,6 +60,4 @@ defi schema "yield opportunities" --results-only defi yield opportunities --chain 1 --asset USDC --timeout 12s --retries 2 --max-stale 5m --results-only ``` -For more copy-paste scenarios, see [Examples Cookbook](/guides/examples-cookbook). - Next: [Output Contract](/concepts/output-contract) From c4456045f17aaaf7db1f1b00dbee073542b0a0b7 Mon Sep 17 00:00:00 2001 From: Gustavo Gonzalez Date: Tue, 24 Feb 2026 16:27:10 -0400 Subject: [PATCH 3/5] docs: add Mintlify versioned docs with v0.2.0 snapshot --- AGENTS.md | 1 + CHANGELOG.md | 1 + README.md | 6 ++ docs.json | 138 +++++++++++++++++--------- legacy/v0-2-0/automation-contract.mdx | 32 ++++++ legacy/v0-2-0/commands-overview.mdx | 47 +++++++++ legacy/v0-2-0/compatibility-notes.mdx | 24 +++++ legacy/v0-2-0/index.mdx | 28 ++++++ legacy/v0-2-0/installation.mdx | 46 +++++++++ legacy/v0-2-0/providers-and-auth.mdx | 31 ++++++ legacy/v0-2-0/quickstart.mdx | 31 ++++++ 11 files changed, 337 insertions(+), 48 deletions(-) create mode 100644 legacy/v0-2-0/automation-contract.mdx create mode 100644 legacy/v0-2-0/commands-overview.mdx create mode 100644 legacy/v0-2-0/compatibility-notes.mdx create mode 100644 legacy/v0-2-0/index.mdx create mode 100644 legacy/v0-2-0/installation.mdx create mode 100644 legacy/v0-2-0/providers-and-auth.mdx create mode 100644 legacy/v0-2-0/quickstart.mdx diff --git a/AGENTS.md b/AGENTS.md index afe90dd..5f71949 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,6 +107,7 @@ README.md # user-facing usage + caveats 1. if adding a feature/command or changing behavior, update Mintlify docs + README + CHANGELOG 2. if changing output schema/fields/exit codes, update contract/reference docs before merge 3. if adding providers/chains/assets/aliases/key requirements, update provider/auth and examples docs + 4. if cutting a release, add/refresh the Mintlify docs version snapshot (for example `vX.Y.Z`) so docs stay aligned with installed CLI versions ## Quality bar diff --git a/CHANGELOG.md b/CHANGELOG.md index 9403df7..4955ed0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,6 +48,7 @@ Format: ### Docs - Updated README and AGENTS guidance for Solana usage, Kamino/Jupiter providers, and API key semantics. - Added a dedicated Mintlify documentation site (`docs.json` + structured MDX pages) with setup, guides, automation patterns, and command reference. +- Added versioned docs navigation with a `v0.2.0` compatibility snapshot so users can select docs by CLI version. - Added a docs CI workflow that runs `mint validate` and `mint broken-links` on docs-related changes. - Refined docs IA by removing overlapping cookbook content, clarifying provider-driven API key requirements, and updating header branding with a lobster wordmark logo. diff --git a/README.md b/README.md index 5ecf6e3..a6ac055 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,10 @@ Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP ## Documentation Site (Mintlify) This repo includes a dedicated Mintlify docs site (`docs.json` + `.mdx` pages at repo root). +The site now uses Mintlify versioned navigation: + +- `latest` -> current default docs +- `v0.2.0` -> archived compatibility snapshot for that CLI release Preview locally: @@ -36,6 +40,8 @@ npx --yes mint@4.2.378 validate npx --yes mint@4.2.378 broken-links ``` +When adding a new CLI release, add/update a version snapshot in docs navigation so users can select docs that match their installed binary. + ## Install ### 1) Quick install (macOS/Linux) diff --git a/docs.json b/docs.json index 8a60479..b08896b 100644 --- a/docs.json +++ b/docs.json @@ -14,71 +14,113 @@ "dark": "/assets/docs-logo-lobster-dark.png" }, "navigation": { - "tabs": [ + "versions": [ { - "tab": "Learn", - "groups": [ + "version": "latest", + "tabs": [ { - "group": "Getting Started", - "pages": [ - "index", - "installation", - "quickstart" + "tab": "Learn", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "index", + "installation", + "quickstart" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "concepts/output-contract", + "concepts/ids-and-amounts", + "concepts/config-and-cache", + "concepts/providers-and-auth" + ] + }, + { + "group": "Workflow Guides", + "pages": [ + "guides/market-discovery", + "guides/lending", + "guides/yield", + "guides/bridge", + "guides/swap" + ] + } ] }, { - "group": "Core Concepts", - "pages": [ - "concepts/output-contract", - "concepts/ids-and-amounts", - "concepts/config-and-cache", - "concepts/providers-and-auth" + "tab": "Agents", + "groups": [ + { + "group": "Automation", + "pages": [ + "agents/overview", + "agents/schema-driven", + "agents/reliability-patterns" + ] + } ] }, { - "group": "Workflow Guides", - "pages": [ - "guides/market-discovery", - "guides/lending", - "guides/yield", - "guides/bridge", - "guides/swap" + "tab": "Reference", + "groups": [ + { + "group": "CLI Commands", + "pages": [ + "reference/commands-overview", + "reference/market-commands", + "reference/lending-and-yield-commands", + "reference/bridge-and-swap-commands", + "reference/meta-commands" + ] + }, + { + "group": "Contracts", + "pages": [ + "reference/envelope-schema", + "reference/exit-codes", + "reference/chain-aliases" + ] + } ] } ] }, { - "tab": "Agents", - "groups": [ + "version": "v0.2.0", + "tabs": [ { - "group": "Automation", - "pages": [ - "agents/overview", - "agents/schema-driven", - "agents/reliability-patterns" - ] - } - ] - }, - { - "tab": "Reference", - "groups": [ - { - "group": "CLI Commands", - "pages": [ - "reference/commands-overview", - "reference/market-commands", - "reference/lending-and-yield-commands", - "reference/bridge-and-swap-commands", - "reference/meta-commands" + "tab": "Learn", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "legacy/v0-2-0/index", + "legacy/v0-2-0/installation", + "legacy/v0-2-0/quickstart" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "legacy/v0-2-0/providers-and-auth", + "legacy/v0-2-0/automation-contract", + "legacy/v0-2-0/compatibility-notes" + ] + } ] }, { - "group": "Contracts", - "pages": [ - "reference/envelope-schema", - "reference/exit-codes", - "reference/chain-aliases" + "tab": "Reference", + "groups": [ + { + "group": "CLI Commands", + "pages": [ + "legacy/v0-2-0/commands-overview" + ] + } ] } ] diff --git a/legacy/v0-2-0/automation-contract.mdx b/legacy/v0-2-0/automation-contract.mdx new file mode 100644 index 0000000..9c773c8 --- /dev/null +++ b/legacy/v0-2-0/automation-contract.mdx @@ -0,0 +1,32 @@ +--- +title: Automation Contract (v0.2.0) +description: Stable envelope, exit codes, and integration notes for v0.2.0. +--- + +`defi-cli` v0.2.0 was already automation-first: + +- Stable JSON envelope (`version`, `success`, `data`, `error`, `warnings`, `meta`) +- Stable process exit codes +- Canonical CAIP-2 / CAIP-19 identifiers + +## Core exit codes + +- `0`: success +- `1`: internal error +- `2`: usage/validation error +- `10`: auth required/failed +- `11`: rate limited +- `12`: provider unavailable +- `13`: unsupported input/provider pair +- `14`: stale data beyond SLA +- `15`: partial results in strict mode +- `16`: blocked by command allowlist + +## Schema support + +Use schema output to build wrappers and validations: + +```bash +defi schema --results-only +defi schema "yield opportunities" --results-only +``` diff --git a/legacy/v0-2-0/commands-overview.mdx b/legacy/v0-2-0/commands-overview.mdx new file mode 100644 index 0000000..a9b7591 --- /dev/null +++ b/legacy/v0-2-0/commands-overview.mdx @@ -0,0 +1,47 @@ +--- +title: Commands Overview (v0.2.0) +description: Top-level command families and common patterns in v0.2.0. +--- + +## Top-level commands + +- `assets` +- `bridge` +- `chains` +- `lend` +- `protocols` +- `providers` +- `schema` +- `swap` +- `version` +- `yield` +- `completion` + +## Common global flags + +- `--json` / `--plain` +- `--results-only` +- `--select` +- `--strict` +- `--timeout` +- `--retries` +- `--max-stale` +- `--no-stale` +- `--no-cache` +- `--enable-commands` +- `--config` + +## Examples + +```bash +defi lend markets --protocol aave --chain 1 --asset USDC --results-only +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only +``` + +For exact flags in your installed binary: + +```bash +defi schema --results-only +defi schema "swap quote" --results-only +``` diff --git a/legacy/v0-2-0/compatibility-notes.mdx b/legacy/v0-2-0/compatibility-notes.mdx new file mode 100644 index 0000000..368d828 --- /dev/null +++ b/legacy/v0-2-0/compatibility-notes.mdx @@ -0,0 +1,24 @@ +--- +title: Compatibility Notes (v0.2.0) +description: What differs between v0.2.0 and latest docs. +--- + +If you run `v0.2.0`, rely on this section instead of `latest` behavior. + +## Not in v0.2.0 + +- Solana command routing and Solana CAIP parsing. +- Kamino lending/yield provider. +- Jupiter swap provider. +- Newer lend/yield retrieval ID fields (`provider_native_id`, `provider_native_id_kind`). +- Bridge quote `fee_breakdown` output. + +## Practical guidance + +- Pin your binary when automating docs + CLI together: + +```bash +defi version --long +``` + +- If your scripts expect newer fields/commands, upgrade the binary first or switch your docs version picker to `latest` and then upgrade accordingly. diff --git a/legacy/v0-2-0/index.mdx b/legacy/v0-2-0/index.mdx new file mode 100644 index 0000000..d70f81f --- /dev/null +++ b/legacy/v0-2-0/index.mdx @@ -0,0 +1,28 @@ +--- +title: defi-cli Docs (v0.2.0) +description: Versioned docs snapshot for CLI v0.2.0. +--- + +This section documents `defi-cli` **v0.2.0** behavior. + +- Release tag: [`v0.2.0`](https://github.com/ggonzalez94/defi-cli/releases/tag/v0.2.0) +- Source README at tag: [`README.md@v0.2.0`](https://github.com/ggonzalez94/defi-cli/blob/v0.2.0/README.md) + +## Feature snapshot + +- Lending and rates from Aave + Morpho (with DefiLlama fallback paths). +- Yield ranking across provider-backed routes. +- Bridge quotes via Across and LiFi. +- Swap quotes via 1inch and Uniswap. +- Chain/protocol discovery and canonical ID resolution. + +## Start here + +- [Installation](/legacy/v0-2-0/installation) +- [Quickstart](/legacy/v0-2-0/quickstart) +- [Providers and Auth](/legacy/v0-2-0/providers-and-auth) +- [Commands Overview](/legacy/v0-2-0/commands-overview) + +## Looking for newer features? + +Use the version picker and switch to `latest` for Solana/Kamino/Jupiter and newer quote/data-model features. diff --git a/legacy/v0-2-0/installation.mdx b/legacy/v0-2-0/installation.mdx new file mode 100644 index 0000000..b371a6b --- /dev/null +++ b/legacy/v0-2-0/installation.mdx @@ -0,0 +1,46 @@ +--- +title: Installation (v0.2.0) +description: Install and configure CLI v0.2.0. +--- + +## Quick install (macOS/Linux) + +```bash +curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh +``` + +Install a specific version: + +```bash +curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh -s -- v0.2.0 +``` + +## Go install + +```bash +go install github.com/ggonzalez94/defi-cli/cmd/defi@v0.2.0 +``` + +## Build from source + +```bash +git clone https://github.com/ggonzalez94/defi-cli.git +cd defi-cli +git checkout v0.2.0 +go build -o defi ./cmd/defi +``` + +## API keys + +In `v0.2.0`, these routes were key-gated by upstream providers: + +- `swap quote --provider 1inch` -> `DEFI_1INCH_API_KEY` +- `swap quote --provider uniswap` -> `DEFI_UNISWAP_API_KEY` +- `chains assets` -> `DEFI_DEFILLAMA_API_KEY` +- `bridge list` / `bridge details` -> `DEFI_DEFILLAMA_API_KEY` + +```bash +export DEFI_1INCH_API_KEY=... +export DEFI_UNISWAP_API_KEY=... +export DEFI_DEFILLAMA_API_KEY=... +``` diff --git a/legacy/v0-2-0/providers-and-auth.mdx b/legacy/v0-2-0/providers-and-auth.mdx new file mode 100644 index 0000000..0035b6c --- /dev/null +++ b/legacy/v0-2-0/providers-and-auth.mdx @@ -0,0 +1,31 @@ +--- +title: Providers and Auth (v0.2.0) +description: Provider capabilities and API key requirements for v0.2.0. +--- + +## Provider matrix + +| Provider | Capabilities | Key required | +| --- | --- | --- | +| `defillama` | chains, protocols, lend/yield fallback, bridge analytics | Route-specific | +| `aave` | lend, yield | No | +| `morpho` | lend, yield | No | +| `across` | bridge quote | No | +| `lifi` | bridge quote | No | +| `1inch` | swap quote | Yes | +| `uniswap` | swap quote | Yes | + +## Key-gated routes + +- `swap quote --provider 1inch` -> `DEFI_1INCH_API_KEY` +- `swap quote --provider uniswap` -> `DEFI_UNISWAP_API_KEY` +- `chains assets` -> `DEFI_DEFILLAMA_API_KEY` +- `bridge list` -> `DEFI_DEFILLAMA_API_KEY` +- `bridge details` -> `DEFI_DEFILLAMA_API_KEY` + +These requirements were driven by provider APIs, not CLI licensing. + +## Routing notes + +- `yield --providers` accepted provider names like `defillama,aave,morpho`. +- Lending and yield paths could route through DefiLlama fallback behavior when direct-provider paths were unavailable. diff --git a/legacy/v0-2-0/quickstart.mdx b/legacy/v0-2-0/quickstart.mdx new file mode 100644 index 0000000..a014091 --- /dev/null +++ b/legacy/v0-2-0/quickstart.mdx @@ -0,0 +1,31 @@ +--- +title: Quickstart (v0.2.0) +description: Common v0.2.0 workflows. +--- + +```bash +defi providers list --results-only +defi chains top --limit 10 --results-only --select rank,chain,tvl_usd +defi chains assets --chain 1 --asset USDC --results-only +defi assets resolve --chain base --symbol USDC --results-only + +defi lend markets --protocol aave --chain 1 --asset USDC --results-only +defi lend rates --protocol morpho --chain 1 --asset USDC --results-only +defi yield opportunities --chain base --asset USDC --limit 20 --results-only +defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --limit 10 --results-only + +defi bridge list --limit 10 --results-only +defi bridge details --bridge layerzero --results-only +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only + +defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only +``` + +`yield opportunities --providers` accepts provider names (`defillama,aave,morpho`). + +Bridge quote examples: + +```bash +defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +defi bridge quote --provider lifi --from 1 --to 8453 --asset USDC --amount 1000000 --results-only +``` From 222cc4ed9c993234717b22fe5288967fcfb6e2b6 Mon Sep 17 00:00:00 2001 From: Gustavo Gonzalez Date: Tue, 24 Feb 2026 17:12:27 -0400 Subject: [PATCH 4/5] docs: move Mintlify site into docs/ and drop version snapshots --- .github/workflows/docs.yml | 14 +- AGENTS.md | 10 +- CHANGELOG.md | 4 +- README.md | 13 +- docs.json | 160 ------------------ {agents => docs/agents}/overview.mdx | 0 .../agents}/reliability-patterns.mdx | 0 {agents => docs/agents}/schema-driven.mdx | 0 .../concepts}/config-and-cache.mdx | 0 .../concepts}/ids-and-amounts.mdx | 0 .../concepts}/output-contract.mdx | 0 .../concepts}/providers-and-auth.mdx | 0 docs/docs.json | 118 +++++++++++++ {guides => docs/guides}/bridge.mdx | 0 {guides => docs/guides}/lending.mdx | 0 {guides => docs/guides}/market-discovery.mdx | 0 {guides => docs/guides}/swap.mdx | 0 {guides => docs/guides}/yield.mdx | 0 {assets => docs/images}/docs-lobster.png | Bin .../images}/docs-logo-lobster-dark.png | Bin .../images}/docs-logo-lobster-light.png | Bin index.mdx => docs/index.mdx | 0 installation.mdx => docs/installation.mdx | 0 quickstart.mdx => docs/quickstart.mdx | 0 .../reference}/bridge-and-swap-commands.mdx | 0 .../reference}/chain-aliases.mdx | 0 .../reference}/commands-overview.mdx | 0 .../reference}/envelope-schema.mdx | 0 {reference => docs/reference}/exit-codes.mdx | 0 .../reference}/lending-and-yield-commands.mdx | 0 .../reference}/market-commands.mdx | 0 .../reference}/meta-commands.mdx | 0 legacy/v0-2-0/automation-contract.mdx | 32 ---- legacy/v0-2-0/commands-overview.mdx | 47 ----- legacy/v0-2-0/compatibility-notes.mdx | 24 --- legacy/v0-2-0/index.mdx | 28 --- legacy/v0-2-0/installation.mdx | 46 ----- legacy/v0-2-0/providers-and-auth.mdx | 31 ---- legacy/v0-2-0/quickstart.mdx | 31 ---- 39 files changed, 134 insertions(+), 424 deletions(-) delete mode 100644 docs.json rename {agents => docs/agents}/overview.mdx (100%) rename {agents => docs/agents}/reliability-patterns.mdx (100%) rename {agents => docs/agents}/schema-driven.mdx (100%) rename {concepts => docs/concepts}/config-and-cache.mdx (100%) rename {concepts => docs/concepts}/ids-and-amounts.mdx (100%) rename {concepts => docs/concepts}/output-contract.mdx (100%) rename {concepts => docs/concepts}/providers-and-auth.mdx (100%) create mode 100644 docs/docs.json rename {guides => docs/guides}/bridge.mdx (100%) rename {guides => docs/guides}/lending.mdx (100%) rename {guides => docs/guides}/market-discovery.mdx (100%) rename {guides => docs/guides}/swap.mdx (100%) rename {guides => docs/guides}/yield.mdx (100%) rename {assets => docs/images}/docs-lobster.png (100%) rename {assets => docs/images}/docs-logo-lobster-dark.png (100%) rename {assets => docs/images}/docs-logo-lobster-light.png (100%) rename index.mdx => docs/index.mdx (100%) rename installation.mdx => docs/installation.mdx (100%) rename quickstart.mdx => docs/quickstart.mdx (100%) rename {reference => docs/reference}/bridge-and-swap-commands.mdx (100%) rename {reference => docs/reference}/chain-aliases.mdx (100%) rename {reference => docs/reference}/commands-overview.mdx (100%) rename {reference => docs/reference}/envelope-schema.mdx (100%) rename {reference => docs/reference}/exit-codes.mdx (100%) rename {reference => docs/reference}/lending-and-yield-commands.mdx (100%) rename {reference => docs/reference}/market-commands.mdx (100%) rename {reference => docs/reference}/meta-commands.mdx (100%) delete mode 100644 legacy/v0-2-0/automation-contract.mdx delete mode 100644 legacy/v0-2-0/commands-overview.mdx delete mode 100644 legacy/v0-2-0/compatibility-notes.mdx delete mode 100644 legacy/v0-2-0/index.mdx delete mode 100644 legacy/v0-2-0/installation.mdx delete mode 100644 legacy/v0-2-0/providers-and-auth.mdx delete mode 100644 legacy/v0-2-0/quickstart.mdx diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ff13141..824c34f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,19 +3,11 @@ name: docs on: push: paths: - - 'docs.json' - - '**/*.mdx' - - 'assets/**' - - 'README.md' - - 'AGENTS.md' + - 'docs/**' - '.github/workflows/docs.yml' pull_request: paths: - - 'docs.json' - - '**/*.mdx' - - 'assets/**' - - 'README.md' - - 'AGENTS.md' + - 'docs/**' - '.github/workflows/docs.yml' workflow_dispatch: @@ -33,7 +25,9 @@ jobs: node-version: '22' - name: Validate docs build + working-directory: docs run: npx --yes mint@${MINT_CLI_VERSION} validate - name: Check broken links + working-directory: docs run: npx --yes mint@${MINT_CLI_VERSION} broken-links diff --git a/AGENTS.md b/AGENTS.md index 5f71949..b8b73af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,8 +54,9 @@ internal/ scripts/install.sh # macOS/Linux installer from GitHub Releases .goreleaser.yml # cross-platform release artifact config assets/ # static assets (logo, images) -docs.json # Mintlify docs site config -*.mdx + concepts/ guides/ ... # Mintlify docs content pages +docs/ # Mintlify docs site + docs.json # Mintlify docs site config + *.mdx + concepts/ guides/ ... # Mintlify docs content pages README.md # user-facing usage + caveats ``` @@ -87,7 +88,7 @@ README.md # user-facing usage + caveats - Amounts used for swaps/bridges are base units; keep both base and decimal forms consistent. - Release artifacts are built on `v*` tags via `.github/workflows/release.yml` and `.goreleaser.yml`. - `scripts/install.sh` installs the latest tagged release artifact into a writable user-space `PATH` directory by default (fallback `~/.local/bin`) and never uses sudo unless explicitly requested. -- Docs site local checks: `npx --yes mint@4.2.378 validate` and `npx --yes mint@4.2.378 broken-links` from repo root. +- Docs site local checks (from `docs/`): `npx --yes mint@4.2.378 validate` and `npx --yes mint@4.2.378 broken-links`. ## Change patterns @@ -107,7 +108,6 @@ README.md # user-facing usage + caveats 1. if adding a feature/command or changing behavior, update Mintlify docs + README + CHANGELOG 2. if changing output schema/fields/exit codes, update contract/reference docs before merge 3. if adding providers/chains/assets/aliases/key requirements, update provider/auth and examples docs - 4. if cutting a release, add/refresh the Mintlify docs version snapshot (for example `vX.Y.Z`) so docs stay aligned with installed CLI versions ## Quality bar @@ -130,6 +130,6 @@ README.md # user-facing usage + caveats ## Maintenance note -- Keep `README.md`, `AGENTS.md`, `CHANGELOG.md`, and Mintlify docs (`docs.json` + `.mdx`) aligned when commands, routing, caveats, or release-relevant behavior change. +- Keep `README.md`, `AGENTS.md`, `CHANGELOG.md`, and Mintlify docs (`docs/docs.json` + `docs/**/*.mdx`) aligned when commands, routing, caveats, or release-relevant behavior change. Do not commit transient binaries like `./defi`. diff --git a/CHANGELOG.md b/CHANGELOG.md index 4955ed0..b013cfa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,8 +47,8 @@ Format: ### Docs - Updated README and AGENTS guidance for Solana usage, Kamino/Jupiter providers, and API key semantics. -- Added a dedicated Mintlify documentation site (`docs.json` + structured MDX pages) with setup, guides, automation patterns, and command reference. -- Added versioned docs navigation with a `v0.2.0` compatibility snapshot so users can select docs by CLI version. +- Added a dedicated Mintlify documentation site (`docs/docs.json` + structured MDX pages) with setup, guides, automation patterns, and command reference. +- Moved Mintlify docs into a dedicated `docs/` directory and simplified navigation to latest-only docs for lower maintenance. - Added a docs CI workflow that runs `mint validate` and `mint broken-links` on docs-related changes. - Refined docs IA by removing overlapping cookbook content, clarifying provider-driven API key requirements, and updating header branding with a lobster wordmark logo. diff --git a/README.md b/README.md index a6ac055..0504b10 100644 --- a/README.md +++ b/README.md @@ -21,27 +21,23 @@ Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP ## Documentation Site (Mintlify) -This repo includes a dedicated Mintlify docs site (`docs.json` + `.mdx` pages at repo root). -The site now uses Mintlify versioned navigation: - -- `latest` -> current default docs -- `v0.2.0` -> archived compatibility snapshot for that CLI release +This repo includes a dedicated Mintlify docs site under [`docs/`](docs) (`docs/docs.json` + `.mdx` pages). Preview locally: ```bash -npx --yes mint dev --no-open +cd docs +npx --yes mint@4.2.378 dev --no-open ``` Validate before publishing: ```bash +cd docs npx --yes mint@4.2.378 validate npx --yes mint@4.2.378 broken-links ``` -When adding a new CLI release, add/update a version snapshot in docs navigation so users can select docs that match their installed binary. - ## Install ### 1) Quick install (macOS/Linux) @@ -286,6 +282,7 @@ internal/ httpx/ # shared HTTP client .github/workflows/ci.yml # CI (test/vet/build) +docs/ # Mintlify docs site (docs.json + MDX pages) AGENTS.md # contributor guide for agents ``` ### Testing diff --git a/docs.json b/docs.json deleted file mode 100644 index b08896b..0000000 --- a/docs.json +++ /dev/null @@ -1,160 +0,0 @@ -{ - "$schema": "https://mintlify.com/docs.json", - "theme": "mint", - "name": "defi-cli", - "description": "Agent-first DeFi retrieval CLI documentation", - "colors": { - "primary": "#0F766E", - "light": "#14B8A6", - "dark": "#0F766E" - }, - "favicon": "/assets/docs-lobster.png", - "logo": { - "light": "/assets/docs-logo-lobster-light.png", - "dark": "/assets/docs-logo-lobster-dark.png" - }, - "navigation": { - "versions": [ - { - "version": "latest", - "tabs": [ - { - "tab": "Learn", - "groups": [ - { - "group": "Getting Started", - "pages": [ - "index", - "installation", - "quickstart" - ] - }, - { - "group": "Core Concepts", - "pages": [ - "concepts/output-contract", - "concepts/ids-and-amounts", - "concepts/config-and-cache", - "concepts/providers-and-auth" - ] - }, - { - "group": "Workflow Guides", - "pages": [ - "guides/market-discovery", - "guides/lending", - "guides/yield", - "guides/bridge", - "guides/swap" - ] - } - ] - }, - { - "tab": "Agents", - "groups": [ - { - "group": "Automation", - "pages": [ - "agents/overview", - "agents/schema-driven", - "agents/reliability-patterns" - ] - } - ] - }, - { - "tab": "Reference", - "groups": [ - { - "group": "CLI Commands", - "pages": [ - "reference/commands-overview", - "reference/market-commands", - "reference/lending-and-yield-commands", - "reference/bridge-and-swap-commands", - "reference/meta-commands" - ] - }, - { - "group": "Contracts", - "pages": [ - "reference/envelope-schema", - "reference/exit-codes", - "reference/chain-aliases" - ] - } - ] - } - ] - }, - { - "version": "v0.2.0", - "tabs": [ - { - "tab": "Learn", - "groups": [ - { - "group": "Getting Started", - "pages": [ - "legacy/v0-2-0/index", - "legacy/v0-2-0/installation", - "legacy/v0-2-0/quickstart" - ] - }, - { - "group": "Core Concepts", - "pages": [ - "legacy/v0-2-0/providers-and-auth", - "legacy/v0-2-0/automation-contract", - "legacy/v0-2-0/compatibility-notes" - ] - } - ] - }, - { - "tab": "Reference", - "groups": [ - { - "group": "CLI Commands", - "pages": [ - "legacy/v0-2-0/commands-overview" - ] - } - ] - } - ] - } - ] - }, - "navbar": { - "links": [ - { - "label": "GitHub", - "href": "https://github.com/ggonzalez94/defi-cli" - } - ], - "primary": { - "type": "button", - "label": "Install", - "href": "https://github.com/ggonzalez94/defi-cli#install" - } - }, - "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude", - "perplexity", - "mcp", - "cursor", - "vscode" - ] - }, - "footer": { - "socials": { - "github": "https://github.com/ggonzalez94/defi-cli" - } - } -} diff --git a/agents/overview.mdx b/docs/agents/overview.mdx similarity index 100% rename from agents/overview.mdx rename to docs/agents/overview.mdx diff --git a/agents/reliability-patterns.mdx b/docs/agents/reliability-patterns.mdx similarity index 100% rename from agents/reliability-patterns.mdx rename to docs/agents/reliability-patterns.mdx diff --git a/agents/schema-driven.mdx b/docs/agents/schema-driven.mdx similarity index 100% rename from agents/schema-driven.mdx rename to docs/agents/schema-driven.mdx diff --git a/concepts/config-and-cache.mdx b/docs/concepts/config-and-cache.mdx similarity index 100% rename from concepts/config-and-cache.mdx rename to docs/concepts/config-and-cache.mdx diff --git a/concepts/ids-and-amounts.mdx b/docs/concepts/ids-and-amounts.mdx similarity index 100% rename from concepts/ids-and-amounts.mdx rename to docs/concepts/ids-and-amounts.mdx diff --git a/concepts/output-contract.mdx b/docs/concepts/output-contract.mdx similarity index 100% rename from concepts/output-contract.mdx rename to docs/concepts/output-contract.mdx diff --git a/concepts/providers-and-auth.mdx b/docs/concepts/providers-and-auth.mdx similarity index 100% rename from concepts/providers-and-auth.mdx rename to docs/concepts/providers-and-auth.mdx diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..0f94d57 --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "defi-cli", + "description": "Agent-first DeFi retrieval CLI documentation", + "colors": { + "primary": "#0F766E", + "light": "#14B8A6", + "dark": "#0F766E" + }, + "favicon": "/images/docs-lobster.png", + "logo": { + "light": "/images/docs-logo-lobster-light.png", + "dark": "/images/docs-logo-lobster-dark.png" + }, + "navigation": { + "tabs": [ + { + "tab": "Learn", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "index", + "installation", + "quickstart" + ] + }, + { + "group": "Core Concepts", + "pages": [ + "concepts/output-contract", + "concepts/ids-and-amounts", + "concepts/config-and-cache", + "concepts/providers-and-auth" + ] + }, + { + "group": "Workflow Guides", + "pages": [ + "guides/market-discovery", + "guides/lending", + "guides/yield", + "guides/bridge", + "guides/swap" + ] + } + ] + }, + { + "tab": "Agents", + "groups": [ + { + "group": "Automation", + "pages": [ + "agents/overview", + "agents/schema-driven", + "agents/reliability-patterns" + ] + } + ] + }, + { + "tab": "Reference", + "groups": [ + { + "group": "CLI Commands", + "pages": [ + "reference/commands-overview", + "reference/market-commands", + "reference/lending-and-yield-commands", + "reference/bridge-and-swap-commands", + "reference/meta-commands" + ] + }, + { + "group": "Contracts", + "pages": [ + "reference/envelope-schema", + "reference/exit-codes", + "reference/chain-aliases" + ] + } + ] + } + ] + }, + "navbar": { + "links": [ + { + "label": "GitHub", + "href": "https://github.com/ggonzalez94/defi-cli" + } + ], + "primary": { + "type": "button", + "label": "Install", + "href": "https://github.com/ggonzalez94/defi-cli#install" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "mcp", + "cursor", + "vscode" + ] + }, + "footer": { + "socials": { + "github": "https://github.com/ggonzalez94/defi-cli" + } + } +} diff --git a/guides/bridge.mdx b/docs/guides/bridge.mdx similarity index 100% rename from guides/bridge.mdx rename to docs/guides/bridge.mdx diff --git a/guides/lending.mdx b/docs/guides/lending.mdx similarity index 100% rename from guides/lending.mdx rename to docs/guides/lending.mdx diff --git a/guides/market-discovery.mdx b/docs/guides/market-discovery.mdx similarity index 100% rename from guides/market-discovery.mdx rename to docs/guides/market-discovery.mdx diff --git a/guides/swap.mdx b/docs/guides/swap.mdx similarity index 100% rename from guides/swap.mdx rename to docs/guides/swap.mdx diff --git a/guides/yield.mdx b/docs/guides/yield.mdx similarity index 100% rename from guides/yield.mdx rename to docs/guides/yield.mdx diff --git a/assets/docs-lobster.png b/docs/images/docs-lobster.png similarity index 100% rename from assets/docs-lobster.png rename to docs/images/docs-lobster.png diff --git a/assets/docs-logo-lobster-dark.png b/docs/images/docs-logo-lobster-dark.png similarity index 100% rename from assets/docs-logo-lobster-dark.png rename to docs/images/docs-logo-lobster-dark.png diff --git a/assets/docs-logo-lobster-light.png b/docs/images/docs-logo-lobster-light.png similarity index 100% rename from assets/docs-logo-lobster-light.png rename to docs/images/docs-logo-lobster-light.png diff --git a/index.mdx b/docs/index.mdx similarity index 100% rename from index.mdx rename to docs/index.mdx diff --git a/installation.mdx b/docs/installation.mdx similarity index 100% rename from installation.mdx rename to docs/installation.mdx diff --git a/quickstart.mdx b/docs/quickstart.mdx similarity index 100% rename from quickstart.mdx rename to docs/quickstart.mdx diff --git a/reference/bridge-and-swap-commands.mdx b/docs/reference/bridge-and-swap-commands.mdx similarity index 100% rename from reference/bridge-and-swap-commands.mdx rename to docs/reference/bridge-and-swap-commands.mdx diff --git a/reference/chain-aliases.mdx b/docs/reference/chain-aliases.mdx similarity index 100% rename from reference/chain-aliases.mdx rename to docs/reference/chain-aliases.mdx diff --git a/reference/commands-overview.mdx b/docs/reference/commands-overview.mdx similarity index 100% rename from reference/commands-overview.mdx rename to docs/reference/commands-overview.mdx diff --git a/reference/envelope-schema.mdx b/docs/reference/envelope-schema.mdx similarity index 100% rename from reference/envelope-schema.mdx rename to docs/reference/envelope-schema.mdx diff --git a/reference/exit-codes.mdx b/docs/reference/exit-codes.mdx similarity index 100% rename from reference/exit-codes.mdx rename to docs/reference/exit-codes.mdx diff --git a/reference/lending-and-yield-commands.mdx b/docs/reference/lending-and-yield-commands.mdx similarity index 100% rename from reference/lending-and-yield-commands.mdx rename to docs/reference/lending-and-yield-commands.mdx diff --git a/reference/market-commands.mdx b/docs/reference/market-commands.mdx similarity index 100% rename from reference/market-commands.mdx rename to docs/reference/market-commands.mdx diff --git a/reference/meta-commands.mdx b/docs/reference/meta-commands.mdx similarity index 100% rename from reference/meta-commands.mdx rename to docs/reference/meta-commands.mdx diff --git a/legacy/v0-2-0/automation-contract.mdx b/legacy/v0-2-0/automation-contract.mdx deleted file mode 100644 index 9c773c8..0000000 --- a/legacy/v0-2-0/automation-contract.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Automation Contract (v0.2.0) -description: Stable envelope, exit codes, and integration notes for v0.2.0. ---- - -`defi-cli` v0.2.0 was already automation-first: - -- Stable JSON envelope (`version`, `success`, `data`, `error`, `warnings`, `meta`) -- Stable process exit codes -- Canonical CAIP-2 / CAIP-19 identifiers - -## Core exit codes - -- `0`: success -- `1`: internal error -- `2`: usage/validation error -- `10`: auth required/failed -- `11`: rate limited -- `12`: provider unavailable -- `13`: unsupported input/provider pair -- `14`: stale data beyond SLA -- `15`: partial results in strict mode -- `16`: blocked by command allowlist - -## Schema support - -Use schema output to build wrappers and validations: - -```bash -defi schema --results-only -defi schema "yield opportunities" --results-only -``` diff --git a/legacy/v0-2-0/commands-overview.mdx b/legacy/v0-2-0/commands-overview.mdx deleted file mode 100644 index a9b7591..0000000 --- a/legacy/v0-2-0/commands-overview.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Commands Overview (v0.2.0) -description: Top-level command families and common patterns in v0.2.0. ---- - -## Top-level commands - -- `assets` -- `bridge` -- `chains` -- `lend` -- `protocols` -- `providers` -- `schema` -- `swap` -- `version` -- `yield` -- `completion` - -## Common global flags - -- `--json` / `--plain` -- `--results-only` -- `--select` -- `--strict` -- `--timeout` -- `--retries` -- `--max-stale` -- `--no-stale` -- `--no-cache` -- `--enable-commands` -- `--config` - -## Examples - -```bash -defi lend markets --protocol aave --chain 1 --asset USDC --results-only -defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only -defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only -``` - -For exact flags in your installed binary: - -```bash -defi schema --results-only -defi schema "swap quote" --results-only -``` diff --git a/legacy/v0-2-0/compatibility-notes.mdx b/legacy/v0-2-0/compatibility-notes.mdx deleted file mode 100644 index 368d828..0000000 --- a/legacy/v0-2-0/compatibility-notes.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Compatibility Notes (v0.2.0) -description: What differs between v0.2.0 and latest docs. ---- - -If you run `v0.2.0`, rely on this section instead of `latest` behavior. - -## Not in v0.2.0 - -- Solana command routing and Solana CAIP parsing. -- Kamino lending/yield provider. -- Jupiter swap provider. -- Newer lend/yield retrieval ID fields (`provider_native_id`, `provider_native_id_kind`). -- Bridge quote `fee_breakdown` output. - -## Practical guidance - -- Pin your binary when automating docs + CLI together: - -```bash -defi version --long -``` - -- If your scripts expect newer fields/commands, upgrade the binary first or switch your docs version picker to `latest` and then upgrade accordingly. diff --git a/legacy/v0-2-0/index.mdx b/legacy/v0-2-0/index.mdx deleted file mode 100644 index d70f81f..0000000 --- a/legacy/v0-2-0/index.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: defi-cli Docs (v0.2.0) -description: Versioned docs snapshot for CLI v0.2.0. ---- - -This section documents `defi-cli` **v0.2.0** behavior. - -- Release tag: [`v0.2.0`](https://github.com/ggonzalez94/defi-cli/releases/tag/v0.2.0) -- Source README at tag: [`README.md@v0.2.0`](https://github.com/ggonzalez94/defi-cli/blob/v0.2.0/README.md) - -## Feature snapshot - -- Lending and rates from Aave + Morpho (with DefiLlama fallback paths). -- Yield ranking across provider-backed routes. -- Bridge quotes via Across and LiFi. -- Swap quotes via 1inch and Uniswap. -- Chain/protocol discovery and canonical ID resolution. - -## Start here - -- [Installation](/legacy/v0-2-0/installation) -- [Quickstart](/legacy/v0-2-0/quickstart) -- [Providers and Auth](/legacy/v0-2-0/providers-and-auth) -- [Commands Overview](/legacy/v0-2-0/commands-overview) - -## Looking for newer features? - -Use the version picker and switch to `latest` for Solana/Kamino/Jupiter and newer quote/data-model features. diff --git a/legacy/v0-2-0/installation.mdx b/legacy/v0-2-0/installation.mdx deleted file mode 100644 index b371a6b..0000000 --- a/legacy/v0-2-0/installation.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Installation (v0.2.0) -description: Install and configure CLI v0.2.0. ---- - -## Quick install (macOS/Linux) - -```bash -curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh -``` - -Install a specific version: - -```bash -curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh -s -- v0.2.0 -``` - -## Go install - -```bash -go install github.com/ggonzalez94/defi-cli/cmd/defi@v0.2.0 -``` - -## Build from source - -```bash -git clone https://github.com/ggonzalez94/defi-cli.git -cd defi-cli -git checkout v0.2.0 -go build -o defi ./cmd/defi -``` - -## API keys - -In `v0.2.0`, these routes were key-gated by upstream providers: - -- `swap quote --provider 1inch` -> `DEFI_1INCH_API_KEY` -- `swap quote --provider uniswap` -> `DEFI_UNISWAP_API_KEY` -- `chains assets` -> `DEFI_DEFILLAMA_API_KEY` -- `bridge list` / `bridge details` -> `DEFI_DEFILLAMA_API_KEY` - -```bash -export DEFI_1INCH_API_KEY=... -export DEFI_UNISWAP_API_KEY=... -export DEFI_DEFILLAMA_API_KEY=... -``` diff --git a/legacy/v0-2-0/providers-and-auth.mdx b/legacy/v0-2-0/providers-and-auth.mdx deleted file mode 100644 index 0035b6c..0000000 --- a/legacy/v0-2-0/providers-and-auth.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Providers and Auth (v0.2.0) -description: Provider capabilities and API key requirements for v0.2.0. ---- - -## Provider matrix - -| Provider | Capabilities | Key required | -| --- | --- | --- | -| `defillama` | chains, protocols, lend/yield fallback, bridge analytics | Route-specific | -| `aave` | lend, yield | No | -| `morpho` | lend, yield | No | -| `across` | bridge quote | No | -| `lifi` | bridge quote | No | -| `1inch` | swap quote | Yes | -| `uniswap` | swap quote | Yes | - -## Key-gated routes - -- `swap quote --provider 1inch` -> `DEFI_1INCH_API_KEY` -- `swap quote --provider uniswap` -> `DEFI_UNISWAP_API_KEY` -- `chains assets` -> `DEFI_DEFILLAMA_API_KEY` -- `bridge list` -> `DEFI_DEFILLAMA_API_KEY` -- `bridge details` -> `DEFI_DEFILLAMA_API_KEY` - -These requirements were driven by provider APIs, not CLI licensing. - -## Routing notes - -- `yield --providers` accepted provider names like `defillama,aave,morpho`. -- Lending and yield paths could route through DefiLlama fallback behavior when direct-provider paths were unavailable. diff --git a/legacy/v0-2-0/quickstart.mdx b/legacy/v0-2-0/quickstart.mdx deleted file mode 100644 index a014091..0000000 --- a/legacy/v0-2-0/quickstart.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Quickstart (v0.2.0) -description: Common v0.2.0 workflows. ---- - -```bash -defi providers list --results-only -defi chains top --limit 10 --results-only --select rank,chain,tvl_usd -defi chains assets --chain 1 --asset USDC --results-only -defi assets resolve --chain base --symbol USDC --results-only - -defi lend markets --protocol aave --chain 1 --asset USDC --results-only -defi lend rates --protocol morpho --chain 1 --asset USDC --results-only -defi yield opportunities --chain base --asset USDC --limit 20 --results-only -defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --limit 10 --results-only - -defi bridge list --limit 10 --results-only -defi bridge details --bridge layerzero --results-only -defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only - -defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only -``` - -`yield opportunities --providers` accepts provider names (`defillama,aave,morpho`). - -Bridge quote examples: - -```bash -defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only -defi bridge quote --provider lifi --from 1 --to 8453 --asset USDC --amount 1000000 --results-only -``` From f9b4fd03135a241770400b4d82c5552c0ea60824 Mon Sep 17 00:00:00 2001 From: Gustavo Gonzalez Date: Tue, 24 Feb 2026 17:28:06 -0400 Subject: [PATCH 5/5] docs: add a11y checks and align heading casing --- .github/workflows/docs.yml | 4 ++++ AGENTS.md | 2 +- README.md | 1 + docs/guides/swap.mdx | 2 +- docs/index.mdx | 2 +- 5 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 824c34f..f17e803 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,3 +31,7 @@ jobs: - name: Check broken links working-directory: docs run: npx --yes mint@${MINT_CLI_VERSION} broken-links + + - name: Check accessibility + working-directory: docs + run: npx --yes mint@${MINT_CLI_VERSION} a11y diff --git a/AGENTS.md b/AGENTS.md index b8b73af..12fcb9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,7 +88,7 @@ README.md # user-facing usage + caveats - Amounts used for swaps/bridges are base units; keep both base and decimal forms consistent. - Release artifacts are built on `v*` tags via `.github/workflows/release.yml` and `.goreleaser.yml`. - `scripts/install.sh` installs the latest tagged release artifact into a writable user-space `PATH` directory by default (fallback `~/.local/bin`) and never uses sudo unless explicitly requested. -- Docs site local checks (from `docs/`): `npx --yes mint@4.2.378 validate` and `npx --yes mint@4.2.378 broken-links`. +- Docs site local checks (from `docs/`): `npx --yes mint@4.2.378 validate`, `npx --yes mint@4.2.378 broken-links`, and `npx --yes mint@4.2.378 a11y`. ## Change patterns diff --git a/README.md b/README.md index 0504b10..bed524b 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ Validate before publishing: cd docs npx --yes mint@4.2.378 validate npx --yes mint@4.2.378 broken-links +npx --yes mint@4.2.378 a11y ``` ## Install diff --git a/docs/guides/swap.mdx b/docs/guides/swap.mdx index 0bc134f..710f209 100644 --- a/docs/guides/swap.mdx +++ b/docs/guides/swap.mdx @@ -36,7 +36,7 @@ defi swap quote --provider jupiter --chain solana --from-asset USDC --to-asset S defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only ``` -## Bungee Auto (keyless default) +## Bungee auto (keyless default) ```bash defi swap quote --provider bungee --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 5000000 --results-only diff --git a/docs/index.mdx b/docs/index.mdx index e604439..06fde25 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -63,7 +63,7 @@ Most commands are keyless. Key requirements are driven by upstream providers, no Bungee quotes are keyless by default. Dedicated backend mode requires both `DEFI_BUNGEE_API_KEY` and `DEFI_BUNGEE_AFFILIATE`. -## Lending and Yield Routing +## Lending and yield routing `lend markets`, `lend rates`, and `yield opportunities` use direct protocol adapters: