defi-cli

Query lending rates, compare yield, get bridge and swap quotes — across protocols and chains, from a single CLI.

Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP-2/CAIP-19), and deterministic exit codes make it easy to pipe into any workflow.

Features

Lending — query markets and rates from Aave, Morpho, and Kamino (Solana).
Yield — compare opportunities across protocols and chains, filter by TVL and APY.
Bridging — get cross-chain quotes (Across, LiFi, Bungee Auto) and bridge analytics (volume, chain breakdown).
Swapping — get on-chain swap quotes (1inch, Uniswap, Jupiter for Solana, Fibrous, Bungee Auto).
Execution IDs — lend/yield rows include provider-scoped provider_native_id plus provider_native_id_kind and provider for safer cross-provider parsing.
Fee transparency — bridge quotes include fee_breakdown (lp_fee, relayer_fee, gas_fee, total_fee_usd) plus consistency checks against amount deltas.
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 under docs/ (docs/docs.json + .mdx pages).

Preview locally:

cd docs
npx --yes mint@4.2.378 dev --no-open

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

Production docs deployment should target docs-live in Mintlify Git settings. The release workflow syncs docs-live to each v* tag so live docs align with released binaries.

Install

1) Quick install (macOS/Linux)

Installs the latest tagged release from GitHub:

curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh

Install a specific version (accepted: latest, stable, vX.Y.Z, X.Y.Z):

curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh -s -- v0.3.1

2) Go install

go install github.com/ggonzalez94/defi-cli/cmd/defi@latest

3) Manual install from release artifacts

Download the right archive from GitHub Releases:
- Linux/macOS: defi_<version>_<os>_<arch>.tar.gz
- Windows: defi_<version>_windows_<arch>.zip
Verify checksums with checksums.txt.
Extract and move defi into your PATH.

4) Build from source

go build -o defi ./cmd/defi

Verify install:

defi version --long

Quick Start

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 # Requires DEFI_DEFILLAMA_API_KEY
defi assets resolve --chain base --asset USDC --results-only
defi assets resolve --chain solana --asset USDC --results-only
defi lend markets --protocol aave --chain 1 --asset USDC --results-only
defi lend markets --protocol kamino --chain solana --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 yield opportunities --chain solana --asset USDC --providers kamino --limit 10 --results-only
defi bridge list --limit 10 --results-only # Requires DEFI_DEFILLAMA_API_KEY
defi bridge details --bridge layerzero --results-only # Requires DEFI_DEFILLAMA_API_KEY
defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only
defi swap quote --chain solana --from-asset USDC --to-asset USDT --amount 1000000 --results-only
defi bridge quote --provider bungee --from hyperevm --to 8453 --asset USDC --amount 1000000 --results-only

yield opportunities --providers accepts provider names from defi providers list (e.g. aave,morpho,kamino).

Bridge quote examples:

defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only # Defaults to Across
defi bridge quote --provider lifi --from 1 --to 8453 --asset USDC --amount 1000000 --results-only
defi bridge quote --provider bungee --from 1 --to 8453 --asset USDC --amount 5000000 --results-only

Swap quote examples:

export DEFI_1INCH_API_KEY=...
export DEFI_UNISWAP_API_KEY=...
defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only
defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only
# Exact-output on Uniswap
defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --type exact-output --amount-out 1000000000000000000 --results-only
# Optional manual slippage override for Uniswap (percent)
defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --slippage-pct 1.0 --results-only
defi swap quote --provider bungee --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 5000000 --results-only

Swap quote example (fibrous does not require an API key):

defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only
 
# On Solana, provider defaults to jupiter.
defi swap quote --chain solana --from-asset USDC --to-asset SOL --amount 1000000 --results-only

Solana identifiers:

Chain: solana (mainnet), or CAIP-2 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Asset (CAIP-19): solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:<mint>
Non-mainnet Solana references (solana-devnet, solana-testnet, custom solana:<ref>) are unsupported.

Command API Key Requirements

Most commands do not require provider API keys.

When a provider requires authentication, bring your own key:

defi swap quote --provider 1inch -> DEFI_1INCH_API_KEY
defi swap quote --provider uniswap -> DEFI_UNISWAP_API_KEY
defi swap quote --provider jupiter -> DEFI_JUPITER_API_KEY (optional for higher limits)
defi swap quote --provider fibrous -> no key required
defi chains assets -> DEFI_DEFILLAMA_API_KEY
defi bridge list -> DEFI_DEFILLAMA_API_KEY
defi bridge details -> DEFI_DEFILLAMA_API_KEY

Bungee quotes (bridge quote --provider bungee, swap quote --provider bungee) are keyless by default. Optional dedicated-backend mode is enabled only when both DEFI_BUNGEE_API_KEY and DEFI_BUNGEE_AFFILIATE are set.

defi providers list includes both provider-level key metadata and capability-level key metadata (capability_auth).

API Keys

DEFI_1INCH_API_KEY (required for swap quote --provider 1inch)
DEFI_UNISWAP_API_KEY (required for swap quote --provider uniswap)
DEFI_JUPITER_API_KEY (optional for swap quote --provider jupiter)
DEFI_DEFILLAMA_API_KEY (required for chains assets, bridge list, and bridge details)
DEFI_BUNGEE_API_KEY + DEFI_BUNGEE_AFFILIATE (optional pair for Bungee dedicated backend on quote routes)

Configure keys with environment variables (recommended):

export DEFI_1INCH_API_KEY=...
export DEFI_UNISWAP_API_KEY=...
export DEFI_JUPITER_API_KEY=...
export DEFI_DEFILLAMA_API_KEY=...
export DEFI_BUNGEE_API_KEY=...
export DEFI_BUNGEE_AFFILIATE=...

For persistent shell setup, add exports to your shell profile (for example ~/.zshrc).

If a keyed provider is used without a key, CLI exits with code 10.

Config (Optional)

Most users only need env vars for provider keys. Use config when you want persistent non-secret defaults (output mode, timeout/retries, cache behavior).

Config precedence is:

flags > env > config file > defaults

Default config path:

${XDG_CONFIG_HOME:-~/.config}/defi/config.yaml

Default cache paths:

${XDG_CACHE_HOME:-~/.cache}/defi/cache.db
${XDG_CACHE_HOME:-~/.cache}/defi/cache.lock

Example optional config:

output: json
strict: false
timeout: 10s
retries: 2
cache:
  enabled: true
  max_stale: 5m

Optional Bungee dedicated-backend config:

providers:
  bungee:
    api_key_env: DEFI_BUNGEE_API_KEY
    affiliate_env: DEFI_BUNGEE_AFFILIATE

Cache Policy

Command TTLs are fixed in code (chains/protocols/chains assets: 5m, lend markets: 60s, lend rates: 30s, yield: 60s, bridge/swap quotes: 15s).
Cache entries are served directly only while fresh (age <= ttl).
After TTL expiry, the CLI fetches provider data immediately.
Cache writes use SQLite WAL + busy timeout + lock/retry backoff to reduce lock contention in parallel agent runs.
If cache initialization fails (path/permission issues), commands continue with cache disabled instead of failing.
cache.max_stale / --max-stale is only a temporary provider-failure fallback window (currently unavailable / rate_limited).
If fallback is disabled (--no-stale or --max-stale 0s) or stale data exceeds the budget, the CLI exits with code 14.
Metadata commands (version, schema, providers list) bypass cache initialization.

Caveats

Morpho can surface extreme APY values on very small markets. Prefer --min-tvl-usd when ranking yield.
Kamino direct adapter currently supports Solana mainnet (solana) only.
Solana devnet/testnet and custom Solana CAIP-2 references are rejected; only Solana mainnet is supported.
provider_native_id is provider-scoped and should be interpreted with provider_native_id_kind (market_id, pool_id, composite_market_asset); do not assume it is an on-chain address.
chains assets requires DEFI_DEFILLAMA_API_KEY because DefiLlama chain asset TVL is key-gated.
bridge list and bridge details require DEFI_DEFILLAMA_API_KEY; quote providers (across, lifi, bungee) are keyless by default.
Across can omit native USD fee fields on some routes; in those cases estimated_fee_usd falls back to a stable-asset approximation and exact token-denominated fees remain in fee_breakdown.
Category rankings from protocols categories are deterministic and sorted by tvl_usd, then protocol count, then name.
--chain normalization supports additional aliases/IDs including mantle, megaeth/mega eth/mega-eth, ink, scroll, berachain, gnosis/xdai, linea, sonic, blast, fraxtal, world-chain, celo, taiko/taiko alethia, zksync, hyperevm/hyper evm/hyper-evm, monad, and citrea.
Bungee Auto-mode quote coverage is chain+token dependent; unsupported pairs return provider errors even when chain normalization succeeds.
Bungee quote requests use deterministic placeholder sender/receiver addresses for quote-only resolution (0x000...001).
Bungee dedicated backend routing only activates when both DEFI_BUNGEE_API_KEY and DEFI_BUNGEE_AFFILIATE are set; if either is missing, requests use the public backend.
Swap quote type defaults to --type exact-input; use --type exact-output with --amount-out/--amount-out-decimal when supported by the provider.
For EVM exact-output requests without --provider, the default provider is uniswap; Solana exact-output is currently unsupported.
Uniswap supports both exact-input and exact-output; 1inch/Jupiter/Fibrous/Bungee currently support exact-input only.
Uniswap quote requests use a deterministic placeholder swapper (0x000...001) and default to provider auto slippage; use --slippage-pct to set a manual max slippage percent.
MegaETH bootstrap symbol parsing currently supports MEGA, WETH, and USDT (USDT maps to the chain's USDT0 contract address). Official Mega token list currently has no Ethereum L1 MEGA token entry.
fibrous swap quotes are currently limited to base, hyperevm, and citrea (monad temporarily disabled due unstable route responses).
For chains without bootstrap symbol entries, pass token address or CAIP-19 via --asset/--from-asset/--to-asset for deterministic resolution.

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

Development

Folder Structure

cmd/
  defi/main.go                    # CLI entrypoint

internal/
  app/runner.go                   # command wiring, routing, cache flow
  providers/                      # external adapters
    aave/ morpho/ kamino/         # direct lending + yield
    defillama/                    # chain/protocol market data + bridge analytics
    across/ lifi/ bungee/         # bridge quotes
    oneinch/ uniswap/ jupiter/ fibrous/ bungee/  # swap
    types.go                      # provider interfaces
  config/                         # file/env/flags precedence
  cache/                          # sqlite cache + file lock
  id/                             # CAIP + amount normalization
  model/                          # envelope + domain models
  out/                            # renderers
  errors/                         # typed errors / exit codes
  schema/                         # machine-readable CLI schema
  policy/                         # command allowlist
  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

go test ./...

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github/workflows		.github/workflows
assets		assets
cmd/defi		cmd/defi
docs		docs
internal		internal
scripts		scripts
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Claude.md		Claude.md
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

defi-cli

Features

Documentation Site (Mintlify)

Install

1) Quick install (macOS/Linux)

2) Go install

3) Manual install from release artifacts

4) Build from source

Quick Start

Command API Key Requirements

API Keys

Config (Optional)

Cache Policy

Caveats

Exit Codes

Development

Folder Structure

Testing

About

Uh oh!

Releases 5

Packages

Contributors 4

Uh oh!

Languages

ggonzalez94/defi-cli

Folders and files

Latest commit

History

Repository files navigation

defi-cli

Features

Documentation Site (Mintlify)

Install

1) Quick install (macOS/Linux)

2) Go install

3) Manual install from release artifacts

4) Build from source

Quick Start

Command API Key Requirements

API Keys

Config (Optional)

Cache Policy

Caveats

Exit Codes

Development

Folder Structure

Testing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Contributors 4

Uh oh!

Languages

Packages