Defi Skills

Multi-step intent: If the request requires multiple actions, present your execution plan to the user before building anything. Explain:

• What steps you will execute and in what order
• What tokens and amounts are involved at each step
• Whether you can build all steps upfront (predictable outputs like stake/wrap) or need to execute step-by-step (unpredictable outputs like swaps)
• Any assumptions you are making (e.g., "I will use the same amount for step 2 since Lido staking is roughly 1:1")

Only proceed after the user confirms the plan. If the user modifies the plan, adjust accordingly.

Ambiguous intent: If the request is vague or could be interpreted multiple ways, ask clarifying questions before doing anything. Do not assume a protocol, token, or strategy. Examples:

• "I want to earn yield on my ETH": Which protocol? Lido staking? Aave supply? Rocket Pool? Each has different risk/reward.
• "Move my stables somewhere safe": Which stablecoins? What does "safe" mean to them? Aave supply? MakerDAO DSR?
• "Do something with my USDC": Too vague. Ask what they want to achieve.

Large amounts or "max": If the user is operating with "max" (entire wallet balance) or amounts you consider significant, confirm the details before building. Remind them that "max" means their entire balance of that token, not just a portion.

Constraints

• Mainnet only (chain_id 1). All contract addresses in playbooks are for mainnet. Do not pass --chain-id. The CLI will reject mismatches.
• One action per CLI call. For multi-step intents, decompose into separate build calls. You are the planner.
• Some actions restrict valid tokens. If you are unsure whether a token is supported for an action, run defi-skills actions <name> --json to check. The CLI will reject unsupported tokens with a clear error listing the valid options.
• Negative amounts are rejected. All amounts must be zero or positive.
• Always check "success" in the JSON response. If success is false, the error field explains what went wrong. Do not proceed with failed builds.
• Some actions have optional parameters with sensible defaults (slippage, fee tier, deadline, recipient address). These are visible via defi-skills actions <name> --json. Inform the user about relevant defaults before building so they can override if needed.

Prerequisites

The CLI must be installed and a wallet address configured:

pip install defi-skills --extra-index-url https://nethermind.jfrog.io/artifactory/api/pypi/kyoto-pypi-local-prod/simple
defi-skills config set-wallet "$WALLET_ADDRESS"

If WALLET_ADDRESS is not set, ask the user to provide their wallet address before continuing.

API keys

Most actions that involve on-chain data need ALCHEMY_API_KEY (ENS resolution, swap quotes, "max" balance queries, EigenLayer strategy verification, etc.). Simple actions with known tokens and fixed amounts (like aave_supply with USDC) work without it.

If a build fails with "no web3 instance" or "no RPC provider available", instruct the user to set their key using the CLI:

defi-skills config set alchemy_api_key "<YOUR_ALCHEMY_KEY>"

Balancer actions additionally need THEGRAPH_API_KEY.

Do not attempt to pass keys via environment variables. Use the config command.

Workflow

Step 1: Identify the Action

Determine the correct action from the supported actions table below. If unsure:

defi-skills actions --json

Step 2: Check Parameters (when needed)

If you are unsure about required parameters or valid tokens for an action:

defi-skills actions aave_supply --json

Step 3: Build the Transaction

TX=$(defi-skills build --action aave_supply --args '{"asset":"USDC","amount":"500"}' --json)

Always check the response before proceeding:

echo "$TX" | jq '.success'        # must be true
echo "$TX" | jq '.transactions'   # ordered array: approvals first, then action

Response Format

The response is a JSON object with success and either transactions (on success) or error (on failure).

On success, transactions is an ordered array. Execute them in order: approval transactions first, then the main action. Some actions need no approval (1 transaction), others need 1 approval (2 transactions), and USDT needs a reset-to-zero step (3 transactions).

{
  "success": true,
  "transactions": [
    {
      "type": "approval",
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "spender": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
      "raw_tx": {
        "chain_id": 1,
        "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "value": "0",
        "data": "0x095ea7b3..."
      }
    },
    {
      "type": "action",
      "action": "aave_supply",
      "target_contract": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
      "function_name": "supply",
      "arguments": {
        "asset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amount": "500000000",
        "onBehalfOf": "0x..."
      },
      "raw_tx": {
        "chain_id": 1,
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "value": "0",
        "data": "0x617ba037..."
      }
    }
  ]
}

On failure: {"success": false, "error": "description of what went wrong"}.

Supported Actions

How to Build Any Action

For every action, follow these three steps in order:

1. Find the action name from the table above. If unsure, list all:

defi-skills actions --json | jq '.by_protocol'

2. Check its parameters (always do this before building):

defi-skills actions <action_name> --json

This returns required and optional fields with exact parameter names and valid tokens. Use these names in --args.

3. Build the transaction:

TX=$(defi-skills build --action <action_name> --args '{"param":"value"}' --json)
echo "$TX" | jq '.success'
echo "$TX" | jq '.transactions'

Examples

Simple: Aave Supply

defi-skills actions aave_supply --json    # check params first
TX=$(defi-skills build --action aave_supply --args '{"asset":"USDC","amount":"1000"}' --json)

Returns 2 transactions: ERC-20 approval, then supply().

ENS Transfer (needs ALCHEMY_API_KEY)

TX=$(defi-skills build --action transfer_native --args '{"to":"vitalik.eth","amount":"0.5"}' --json)

Multi-step: Stake then Restake

Lido staking is predictable (~1:1), so build both upfront:

TX1=$(defi-skills build --action lido_stake --args '{"amount":"10"}' --json)
TX2=$(defi-skills build --action eigenlayer_deposit --args '{"asset":"stETH","amount":"10"}' --json)

Multi-Step Planning

The CLI is stateless. Each build call is independent with no memory of previous calls and no way to reference the output of a prior transaction. When planning multi-step intents:

• Predictable outputs (stake, wrap, supply): input roughly equals output. Build all steps upfront with the same amount. Example: stake 10 ETH on Lido produces ~10 stETH, so pass "amount":"10" to the EigenLayer deposit.
• Unpredictable outputs (swaps, complex withdrawals): the output depends on live prices or on-chain state. You cannot know the exact amount at build time. Build and execute step 1 first, then ask the user for the result or check on-chain before building step 2. Do not guess amounts.
• "max" means entire wallet balance, not "whatever came from the last step." If the user already holds the token, "max" will include their existing balance plus the new amount. Make sure the user understands this before using it.

Error Handling

• success: false: Read the error field. Do not retry blindly. Fix the input based on the error message.
• Unknown action: Run defi-skills actions to see all supported actions.
• Unsupported token: The error lists valid tokens for the action.
• Chain ID mismatch: All playbooks are mainnet-only. Do not pass --chain-id.
• Negative amount: Amounts must be zero or positive.
• ENS resolution failed: The user needs to run defi-skills config set alchemy_api_key <KEY>, or provide a hex address instead.
• Missing wallet: Run defi-skills config set-wallet <address>.
• CLI not found: Run npm install defi-skills --registry https://nethermind.jfrog.io/artifactory/api/npm/.

Safety

• Output is an unsigned transaction. The tool never signs or broadcasts.
• No private keys are involved at any stage.
• The deterministic build path (--action + --args) uses zero LLM tokens.
• Always review the raw_tx before signing. Verify to, value, and data.