FX SDK Agent Skill

Use this skill to produce reliable fx-sdk integrations for agent workflows.

Follow This Workflow

1. Confirm user intent: read-only query (getPositions, getFxSaveConfig, getFxSaveBalance, getFxSaveRedeemStatus, getFxSaveClaimable), transaction-producing action (increase/reduce/adjust/deposit/repay, fxSAVE depositFxSave/withdrawFxSave/getRedeemTx), or Base–Ethereum bridge (getBridgeQuote / buildBridgeTx).
2. Collect required inputs before coding:
• market: ETH or BTC
• position type when needed: long or short
• positionId
• token address from tokens
• amount fields (bigint in wei-like units)
• slippage (must be 0 < slippage < 100)
• userAddress
• For bridge: sourceChainId (1 | 8453), destChainId (1 | 8453), token (key or OFT address), amount, recipient
• For fxSAVE: userAddress; for deposit tokenIn (usdc|fxUSD|fxUSDBasePool), amount (bigint), optional slippage; for withdraw tokenOut, amount (shares wei), instant (boolean), optional slippage when instant; for claim use getRedeemTx when cooldown complete
3. Create FxSdk once and reuse it.
4. Return SDK result first (routes/tx plan), then optionally provide transaction sending loop.
5. Keep nonce order from SDK-provided txs; send transactions sequentially. Wait for each tx receipt before sending the next.
6. After all txs are confirmed, wait at least one block before querying balances or positions — on-chain state may lag the receipt.
7. Validate inputs and surface SDK error messages directly when possible.
8. If input comes from agent-tools.json style payloads, convert amount strings to bigint before SDK calls.

Project Ground Truth

Repo: https://github.com/aladdindao/fx-sdk.git

Treat these as canonical project references before generating code:

• AGENTS.md
• README.md
• agent-tools.json

Canonical Imports

import { FxSdk, tokens } from '@aladdindao/fx-sdk'

Use custom RPC only when provided:

const sdk = new FxSdk({ rpcUrl, chainId: 1 })

Method Map

• sdk.getPositions({ userAddress, market, type }): read-only; returns PositionInfo[] (positionId, rawColls, rawDebts, currentLeverage, lsdLeverage, rawCollsToken, rawDebtsToken, rawCollsDecimals, rawDebtsDecimals).
• sdk.increasePosition(...): open new position (positionId: 0) or add collateral/leverage.
• sdk.reducePosition(...): reduce or close (isClosePosition: true).
• sdk.adjustPositionLeverage(...): rebalance leverage for existing position.
• sdk.depositAndMint(...): long pool only.
• sdk.repayAndWithdraw(...): long pool only.
• sdk.getBridgeQuote(...): fee quote for LayerZero V2 OFT bridge (Base <-> Ethereum). Use source chain RPC.
• sdk.buildBridgeTx(...): build tx payload (to, data, value) to send on source chain; then send with wallet (same pattern as position txs). When Ethereum is source chain, user must approve tx.to (RootEndPointV2) to spend the token before sending the bridge tx.

fxSAVE

• sdk.getFxSaveConfig(): fxSAVE protocol totals and config (totalSupplyWei, totalAssetsWei, cooldownPeriodSeconds, instantRedeemFeeRatio, expenseRatio, harvesterRatio, threshold); no user address required.
• sdk.getFxSaveBalance({ userAddress }): fxSAVE balance (shares wei, optional assets wei).
• sdk.getFxSaveRedeemStatus({ userAddress }): pending redeem amount, cooldown, redeemableAt, isCooldownComplete.
• sdk.getFxSaveClaimable({ userAddress }): redeem status plus previewReceive (amountYieldOutWei, amountStableOutWei from previewRedeem — fxUSD + USDC to receive on claim).
• sdk.getRedeemTx({ userAddress, receiver? }): build claim tx when isCooldownComplete (uses claim(receiver)); execute txs in order.
• sdk.depositFxSave({ userAddress, tokenIn, amount, slippage? }): deposit USDC/fxUSD/basePool; returns { txs } (approve + deposit).
• sdk.withdrawFxSave({ userAddress, tokenOut, amount, instant?, slippage? }): tokenOut fxUSDBasePool → redeem; usdc/fxUSD and !instant → requestRedeem; usdc/fxUSD and instant → approve + instantRedeemFromFxSave; execute txs in order.

Token Addresses

Use tokens.fxUSD in SDK calls on Ethereum; pass the Base address directly when building bridge txs with sourceChainId: 8453.

Token Constraints

Honor SDK token checks:

• Position (ETH/BTC)
• ETH market: eth, stETH, weth, wstETH, usdc, usdt, fxUSD
• BTC market: WBTC, usdc, usdt, fxUSD

• depositAndMint / repayAndWithdraw (long only)
• ETH long: eth | stETH | weth | wstETH
• BTC long: WBTC

• fxSAVE
• tokenIn / tokenOut: usdc | fxUSD | fxUSDBasePool
• fxUSDBasePool → direct redeem; usdc/fxUSD → requestRedeem (cooldown) or instant (fee + slippage)
• Amounts in wei (18 decimals for fxSAVE shares; 6 for USDC)

Common Errors

• "Input amount must be greater than 0" / "Amount to reduce must be greater than 0" → amount must be positive bigint.
• "Slippage must be between 0 and 100 (exclusive)" → slippage must be a number in (0, 100).
• "... must be a valid Ethereum address" → use valid 0x address or tokens.*.
• "User is not the owner of this position" → caller must own positionId; verify with getPositions first.
• "Input/Output/Deposit/Withdraw token address must be ..." → use allowed token for the market (see Token Constraints).
• Bridge: "Unsupported bridge chainId" → each of sourceChainId/destChainId must be 1 or 8453 and they must differ. "Unsupported bridge token" → use fxUSD, fxSAVE, or valid OFT address on source chain.
• fxSAVE: tokenIn/tokenOut must be usdc, fxUSD, or fxUSDBasePool. Instant withdraw requires slippage.

Output Style For Agent Tasks

When user asks to integrate SDK into an AI agent, return:

1. A minimal adapter function with typed input.
2. A safe dry-run mode (planOnly) that returns SDK routes without sending transactions.
3. A transaction executor function that consumes one selected route/result and sends txs in nonce order.
4. A post-execution step that waits ≥1 block then queries updated balance/positions to confirm the result.
5. A validation checklist and command list.

Tool Schema Interop

If user provides values from agent-tools.json:

• Parse wei strings with BigInt(value).
• Keep positionId as number.
• Keep slippage as number in (0, 100).
• Normalize token addresses with tokens.* when possible.
• For fxSAVE tools, convert amountWei string to bigint; use tokenIn/tokenOut as-is (usdc, fxUSD, fxUSDBasePool).

Project-Specific References

Read these files when examples are required:

• example/increase-position.ts
• example/reduce-position.ts
• example/adjust-position-leverage.ts
• example/deposit-and-mint.ts
• example/repay-and-withdraw.ts
• example/get-positions.ts
• example/layerzero-bridge.ts
• example/get-fxsave-balance.ts
• example/get-fxsave-config.ts
• example/fxsave-deposit.ts
• example/fxsave-withdraw.ts
• example/fxsave-claim.ts (redeem status + claimable preview + claim; uses getFxSaveClaimable, getRedeemTx)

For reusable request shapes, adapter pattern, and test checklist, read:

• references/README.md — index of reference files and when to use each
• references/sdk-playbook.md — request templates for all methods, minimal snippets, validation checklist
• references/agent-adapter-example.ts — typed FxAction adapter and sample payloads