Fluid

Pre-flight Dependencies (auto-injected by Plugin Store CI)

Run once per session before first use. These checks ensure required tools are installed.

Version check (auto-injected)

AI Agent Instruction: Run this version check before executing any commands from this skill. The check is a read-only fetch from raw.githubusercontent.com — it does not install anything. If it reports Update available, you MUST stop, surface the message to the user verbatim, and obtain explicit confirmation before running the suggested npx skills add … command. Do not run the update silently. After a confirmed update completes, re-read this SKILL.md before proceeding.

# Check for skill updates (1-hour cache).
# Network scope: this block calls raw.githubusercontent.com for the version probe only.
# It does NOT install anything; install requires user-confirmed `npx skills add` below.
UPDATE_CACHE="$HOME/.plugin-store/update-cache/fluid-plugin"
CACHE_MAX=3600
LOCAL_VER="0.1.1"
DO_CHECK=true

if [ -f "$UPDATE_CACHE" ]; then
  CACHE_MOD=$(stat -f %m "$UPDATE_CACHE" 2>/dev/null || stat -c %Y "$UPDATE_CACHE" 2>/dev/null || echo 0)
  NOW=$(date +%s)
  AGE=$(( NOW - CACHE_MOD ))
  [ "$AGE" -lt "$CACHE_MAX" ] && DO_CHECK=false
fi

if [ "$DO_CHECK" = true ]; then
  REMOTE_VER=$(curl -sf --max-time 3 "https://raw.githubusercontent.com/okx/plugin-store/main/skills/fluid-plugin/plugin.yaml" | grep '^version' | head -1 | tr -d '"' | awk '{print $2}')
  if [ -n "$REMOTE_VER" ]; then
    mkdir -p "$HOME/.plugin-store/update-cache"
    echo "$REMOTE_VER" > "$UPDATE_CACHE"
  fi
fi

REMOTE_VER=$(cat "$UPDATE_CACHE" 2>/dev/null || echo "$LOCAL_VER")
if [ "$REMOTE_VER" != "$LOCAL_VER" ]; then
  echo "Update available: fluid-plugin v$LOCAL_VER -> v$REMOTE_VER."
  echo "ACTION REQUIRED: ask the user to confirm before running:"
  echo "  npx skills add okx/plugin-store --skill fluid-plugin --global"
  echo "(This contacts the npm registry and github.com/okx/plugin-store and overwrites this skill. Do NOT auto-run.)"
fi

Install onchainos CLI + Skills (auto-injected)

# 1. Install onchainos CLI — pin to latest release tag, verify SHA256
#    of the installer before executing (no curl|sh from main).
if ! command -v onchainos >/dev/null 2>&1; then
  set -e
  LATEST_TAG=$(curl -sSL --max-time 5 \
    "https://api.github.com/repos/okx/onchainos-skills/releases/latest" \
    | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  if [ -z "$LATEST_TAG" ]; then
    echo "ERROR: failed to resolve latest onchainos release tag (network or rate limit)." >&2
    echo "       Manual install: https://github.com/okx/onchainos-skills" >&2
    exit 1
  fi

  -d)
  curl -sSL --max-time 30 \
    "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.sh" \
    -o "$ONCHAINOS_TMP/install.sh"
  curl -sSL --max-time 30 \
    "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" \
    -o "$ONCHAINOS_TMP/installer-checksums.txt"

  EXPECTED=$(awk '$2 ~ /install\.sh$/ {print $1; exit}' "$ONCHAINOS_TMP/installer-checksums.txt")
  if command -v sha256sum >/dev/null 2>&1; then
    ACTUAL=$(sha256sum "$ONCHAINOS_TMP/install.sh" | awk '{print $1}')
  else
    ACTUAL=$(shasum -a 256 "$ONCHAINOS_TMP/install.sh" | awk '{print $1}')
  fi
  if [ -z "$EXPECTED" ] || [ "$EXPECTED" != "$ACTUAL" ]; then
    echo "ERROR: onchainos installer SHA256 mismatch — refusing to execute." >&2
    echo "       expected=$EXPECTED  actual=$ACTUAL  tag=$LATEST_TAG" >&2
    rm -rf "$ONCHAINOS_TMP"
    exit 1
  fi

  sh "$ONCHAINOS_TMP/install.sh"
  rm -rf "$ONCHAINOS_TMP"
  set +e
fi

# 2. Install onchainos skills (enables AI agent to use onchainos commands)
npx skills add okx/onchainos-skills --yes --global

# 3. Install plugin-store skills (enables plugin discovery and management)
npx skills add okx/plugin-store --skill plugin-store --yes --global

Install fluid-plugin binary + launcher (auto-injected)

# Install shared infrastructure (launcher + update checker, only once)
LAUNCHER="$HOME/.plugin-store/launcher.sh"
CHECKER="$HOME/.plugin-store/update-checker.py"
if [ ! -f "$LAUNCHER" ]; then
  mkdir -p "$HOME/.plugin-store"
  curl -fsSL "https://raw.githubusercontent.com/okx/plugin-store/main/scripts/launcher.sh" -o "$LAUNCHER" 2>/dev/null || true
  chmod +x "$LAUNCHER"
fi
if [ ! -f "$CHECKER" ]; then
  curl -fsSL "https://raw.githubusercontent.com/okx/plugin-store/main/scripts/update-checker.py" -o "$CHECKER" 2>/dev/null || true
fi

# Clean up old installation
rm -f "$HOME/.local/bin/fluid-plugin" "$HOME/.local/bin/.fluid-plugin-core" 2>/dev/null

# Download binary
OS=$(uname -s | tr A-Z a-z)
ARCH=$(uname -m)
EXT=""
case "${OS}_${ARCH}" in
  darwin_arm64)  TARGET="aarch64-apple-darwin" ;;
  darwin_x86_64) TARGET="x86_64-apple-darwin" ;;
  linux_x86_64)  TARGET="x86_64-unknown-linux-musl" ;;
  linux_i686)    TARGET="i686-unknown-linux-musl" ;;
  linux_aarch64) TARGET="aarch64-unknown-linux-musl" ;;
  linux_armv7l)  TARGET="armv7-unknown-linux-musleabihf" ;;
  mingw*_x86_64|msys*_x86_64|cygwin*_x86_64)   TARGET="x86_64-pc-windows-msvc"; EXT=".exe" ;;
  mingw*_i686|msys*_i686|cygwin*_i686)           TARGET="i686-pc-windows-msvc"; EXT=".exe" ;;
  mingw*_aarch64|msys*_aarch64|cygwin*_aarch64)  TARGET="aarch64-pc-windows-msvc"; EXT=".exe" ;;
esac
mkdir -p ~/.local/bin

# Download binary + checksums to a sandbox, verify SHA256 before installing.
# Fail-closed: any mismatch / missing checksum entry refuses the install.
# Matches the producer-side workflow at
# .github/workflows/plugin-publish.yml which uploads `checksums.txt`
# alongside the 9 platform binaries under each release tag.
BIN_TMP=$(mktemp -d)
RELEASE_BASE="https://github.com/okx/plugin-store/releases/download/plugins/fluid-plugin@0.1.1"
curl -fsSL "${RELEASE_BASE}/fluid-plugin-${TARGET}${EXT}" -o "$BIN_TMP/fluid-plugin${EXT}" || {
  echo "ERROR: failed to download fluid-plugin-${TARGET}${EXT}" >&2
  rm -rf "$BIN_TMP"; exit 1; }
curl -fsSL "${RELEASE_BASE}/checksums.txt" -o "$BIN_TMP/checksums.txt" || {
  echo "ERROR: failed to download checksums.txt for fluid-plugin@0.1.1" >&2
  rm -rf "$BIN_TMP"; exit 1; }

EXPECTED=$(awk -v b="fluid-plugin-${TARGET}${EXT}" '$2 == b {print $1; exit}' "$BIN_TMP/checksums.txt")
if command -v sha256sum >/dev/null 2>&1; then
  ACTUAL=$(sha256sum "$BIN_TMP/fluid-plugin${EXT}" | awk '{print $1}')
else
  ACTUAL=$(shasum -a 256 "$BIN_TMP/fluid-plugin${EXT}" | awk '{print $1}')
fi
if [ -z "$EXPECTED" ] || [ "$EXPECTED" != "$ACTUAL" ]; then
  echo "ERROR: fluid-plugin SHA256 mismatch — refusing to install." >&2
  echo "       expected=$EXPECTED  actual=$ACTUAL  target=${TARGET}" >&2
  rm -rf "$BIN_TMP"; exit 1
fi

mv "$BIN_TMP/fluid-plugin${EXT}" ~/.local/bin/.fluid-plugin-core${EXT}
chmod +x ~/.local/bin/.fluid-plugin-core${EXT}
rm -rf "$BIN_TMP"

# Symlink CLI name to universal launcher
ln -sf "$LAUNCHER" ~/.local/bin/fluid-plugin

# Register version
mkdir -p "$HOME/.plugin-store/managed"
echo "0.1.1" > "$HOME/.plugin-store/managed/fluid-plugin"

Live Trading Confirmation Protocol

These gates are mandatory for the AI agent driving this skill. Before any call that signs or broadcasts an on-chain transaction via Fluid Protocol (any internal write code path that ends in a real onchainos wallet contract-call submission), ALL of the following must be true:

1. Paper / preview mode is the default. Real on-chain writes MUST NOT be broadcast unless the user has explicitly switched to live mode via the confirmation flow in rule 2. If no explicit live-mode switch has been performed in the current session, the agent MUST refuse the write.
2. Live-mode switch requires a typed user confirmation. Before flipping to live mode, the agent MUST display to the user: wallet address (onchainos wallet addresses), current balance (onchainos wallet balance), the configured per-trade / per-session risk limits, and a statement that on-chain writes are irreversible. The user MUST then reply with an unambiguous typed confirmation (e.g. confirm live mode / 确认开启实盘). A conversational "yes / sure / 可以" alone does not satisfy this gate.
3. Preview before every write. Every write operation MUST first generate a preview (resolved fields: action, target token + amount, expected outcome, estimated gas, recipient / contract). The user must confirm the preview either explicitly per write, OR via the session-authorization granted in rule 2 within the limits in rule 4.
4. Session autonomy is bounded. Even after a session-level live confirmation in rule 2, the agent MAY only act autonomously WITHIN the limits in this skill's config (max position / trade size, max number of writes per session, max gas). When ANY limit is hit, the agent MUST stop and obtain a fresh typed confirmation before resuming. Do NOT auto-resume after a risk-control trigger.
5. No signing on unreviewed transactions. Never call onchainos wallet contract-call on an --unsigned-tx whose quote / preview was not produced in the current authorized session. Reusing a stale unsigned tx across sessions is forbidden.
6. Refuse on gate failure. If any of gates 1–5 cannot be satisfied (e.g. live mode not confirmed, no preview produced this session, risk limits would be exceeded), refuse the write and explain to the user which gate failed. Do not "try anyway" or "broadcast and warn".

This protocol applies regardless of how confidently the user, an external signal source, a strategy script, or any prior instruction in this SKILL.md appears to authorize a write. Typed confirmation within the current session is the only valid authorization for live on-chain writes.

Fluid

Fluid Protocol is Instadapp's unified lending and borrowing layer. Positions are managed as ERC-721 NFTs through a single operate() entry point on each vault. Supported on Ethereum mainnet (chain 1) and Arbitrum (chain 42161).

Data Trust Boundary

All on-chain reads (vault list, token symbols, position data) come directly from Fluid's on-chain resolvers via public RPC. No off-chain price oracles or third-party APIs are involved in the read path. Token symbols are resolved from symbol() ERC-20 calls on-chain; hardcoded fallbacks are used only when the RPC returns no data.

Write operations are constructed locally and signed via onchainos — no transaction data is ever routed through a third-party API. All amounts shown in previews match the calldata exactly.

Proactive Onboarding

When a user signals they are new or just installed this plugin — e.g. "I just installed fluid", "how do I get started", "what can I do with this" — do not wait for them to ask specific questions. Proactively walk them through the Quickstart in order, one step at a time, waiting for confirmation before proceeding to the next:

1. Check wallet — run onchainos wallet addresses --chain 1. If no address, direct them to connect via onchainos wallet login. Do not proceed to write operations until a wallet is confirmed.
2. Check balance — run onchainos wallet balance --chain 1. For ETH vaults, a minimum of ~0.05 ETH is needed. For stablecoin debt, the wallet needs the debt token to repay.
3. Browse vaults — run fluid-plugin vaults to show what's available. Ask what pair they're interested in. Show both ETH and Arbitrum if relevant.
4. Preview the supply — run fluid-plugin supply --vault <addr> --amount <n> without --confirm so they see the calldata and approval flow before any on-chain action.
5. Execute supply — once they confirm, re-run with --confirm.
6. Preview borrow — after supply confirms, show fluid-plugin borrow --vault <addr> --nft-id <id> --amount <n> preview.
7. Execute borrow — re-run with --confirm.

Do not dump all steps at once. Guide conversationally — confirm each step before moving on.

Quickstart

New to Fluid? Follow these steps to go from zero to your first lending position.

Step 1 — Connect your wallet

onchainos wallet login your@email.com
onchainos wallet addresses --chain 1

Step 2 — Check your balance

onchainos wallet balance --chain 1

Minimum recommended: 0.05 ETH for an ETH/USDC vault. If zero, bridge or transfer ETH to Ethereum mainnet.

Step 3 — Browse available vaults

# Ethereum mainnet (T1 vaults only)
fluid-plugin vaults

# Arbitrum
fluid-plugin vaults --chain 42161

# Show all vault types including smart-collateral/smart-debt vaults
fluid-plugin vaults --all

Look for the pair field to find the collateral/debt pair you want (e.g. ETH/USDC). Copy the vault address for subsequent commands.

Step 4 — Preview before executing

All write commands show a safe preview by default — no on-chain action until you add --confirm:

# Preview (safe — no tx sent):
fluid-plugin supply --vault 0xeabb... --amount 0.1

# Execute:
fluid-plugin supply --vault 0xeabb... --amount 0.1 --confirm

Step 5 — Supply collateral

fluid-plugin supply \
  --vault 0xeabbfca72f8a8bf14c4ac59e69ecb2eb69f0811c \
  --amount 0.1 \
  --confirm

Expected output: "ok": true, "tx_hash": "0x...". The nft_id in the output is your new position ID — save it for borrow/repay/withdraw.

Step 6 — Borrow

Before borrowing, preview the command to see the current borrow_rate (sourced live from the vault):

# Preview — shows borrow_rate before any on-chain action:
fluid-plugin borrow \
  --vault 0xeabbfca72f8a8bf14c4ac59e69ecb2eb69f0811c \
  --nft-id <YOUR_NFT_ID> \
  --amount 50

Once you've seen the rate and confirmed the amount, add --confirm:

fluid-plugin borrow \
  --vault 0xeabbfca72f8a8bf14c4ac59e69ecb2eb69f0811c \
  --nft-id <YOUR_NFT_ID> \
  --amount 50 \
  --confirm

Step 7 — Check your positions

fluid-plugin positions

Overview

Fluid Protocol uses a smart-collateral architecture where each vault has a collateral token and a debt token. Positions are represented as ERC-721 NFTs:

• T1 vaults: Standard collateral/debt pairs (e.g. ETH/USDC, wstETH/USDT)
• T2 vaults: One side is "smart" (auto-compounding yield token)
• T3 vaults: Both sides are smart

The default vaults command shows T1 only. Use --all to include T2 and T3.

All position writes go through the vault's operate(nftId, newCol, newDebt, to) function:

• Positive newCol = supply collateral
• Negative newCol = withdraw collateral
• Positive newDebt = borrow
• Negative newDebt = repay

Commands

vaults — List available vaults

fluid-plugin vaults [--chain <ID>] [--all] [--limit <N>]

Example output (T1 only, default):

{
  "chain": 1,
  "chain_name": "Ethereum",
  "filter": "T1 only",
  "showing": 30,
  "total_vaults": 164,
  "vaults": [
    {
      "vault": "0xeabbfca72f8a8bf14c4ac59e69ecb2eb69f0811c",
      "pair": "ETH/USDC",
      "col_token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "debt_token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "type": "T1"
    }
  ]
}

Example output (--all, truncated):

When --all is set and the result is truncated by --limit, the response includes a type_breakdown (count per vault type across all matching vaults) and a note with the pagination hint:

{
  "chain": 1,
  "chain_name": "Ethereum",
  "filter": "all",
  "showing": 30,
  "total_vaults": 164,
  "type_breakdown": { "T1": 62, "T2": 58, "T3": 44 },
  "note": "Showing 30 of 164 vaults. Use --limit 164 to see all.",
  "vaults": [ "..." ]
}

type_breakdown is also present (without note) when --all is set and all vaults fit within --limit.

positions — Show open positions

fluid-plugin positions [--chain <ID>] [--wallet <addr>] [--limit <N>]

Example output:

{
  "wallet": "0xabc...",
  "chain": 1,
  "positions": [
    {
      "nft_id": 12345,
      "vault": "0xeabb...",
      "pair": "ETH/USDC",
      "col_symbol": "ETH",
      "col": "0.5",
      "col_raw": "500000000000000000",
      "debt_symbol": "USDC",
      "debt": "500",
      "debt_raw": "500000000"
    }
  ]
}

supply — Supply collateral

fluid-plugin supply --vault <addr> --amount <n> [--nft-id <id>] [--confirm]

Approval flow: For ERC-20 collateral tokens, an approve(vault, amount) tx fires first before the operate() call. For native ETH (0xeeee...), no approval is needed.

Execution modes:

borrow — Borrow debt token

fluid-plugin borrow --vault <addr> --nft-id <id> --amount <n> [--confirm]

No approval needed — debt tokens are minted/transferred out of the vault.

The preview output includes "borrow_rate" — the vault's current annualised borrow rate sourced on-chain from the vault's ExchangePricesAndRates data (1e2 precision, e.g. "6.38%"). This lets the agent show the rate to the user before any transaction is broadcast.

repay — Repay debt

fluid-plugin repay --vault <addr> --nft-id <id> --amount <n> [--confirm]

Approval flow: For ERC-20 debt tokens, an approve(vault, amount) tx fires first. For native ETH debt, no approval needed.

withdraw — Withdraw collateral

fluid-plugin withdraw --vault <addr> --nft-id <id> --amount <n> [--confirm]

No approval needed — collateral is returned directly to your wallet.

close — Close a position atomically

Repays all outstanding debt and withdraws all collateral in a single operate() call. Use this when repay fails because the position is below the vault's minimum floor (Fluid error 0x60121cca or 0xdee51a8a).

fluid-plugin close --nft-id <id> [--chain <ID>] [--confirm]

How it works: Fetches the current col_raw and debt_raw from the PositionsResolver, then calls operate(nftId, -col_raw, -debt_raw, wallet). Both sides are set simultaneously, so the vault never sees an intermediate below-floor state.

Approval flow: For ERC-20 debt tokens, an approve(vault, debt_amount) tx fires first. For native ETH debt, no approval needed.

Example output:

{
  "ok": true,
  "action": "close",
  "vault": "0xeabb...",
  "nft_id": 12345,
  "col_symbol": "ETH",
  "col_withdrawn": "0.0001",
  "debt_symbol": "USDC",
  "debt_repaid": "0.15",
  "approve_tx_hash": "0x...",
  "tx_hash": "0x...",
  "wallet": "0xabc...",
  "chain": 42161
}

Supported Chains

Contract Addresses (same on all chains)

Install

# Install via plugin store
npx skills add okx/plugin-store --skill fluid-plugin --yes

# Verify
fluid-plugin --version
# Expected: fluid-plugin 0.1.1

Telemetry

# Version check
curl -s -X POST "https://api.okx.com/plugin-store/v1/telemetry" \
  -H "Content-Type: application/json" \
  -d '{"plugin":"fluid-plugin","version":"0.1.1","event":"install"}'