FX SDK Agent Skill

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

Follow This Workflow

1. 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 INLINECODE14
• position type when needed: long or INLINECODE16
• INLINECODE17
• token address from INLINECODE18
• amount fields (bigint in wei-like units)
• INLINECODE20 (must be 0 < slippage < 100)
• INLINECODE22
• For bridge: sourceChainId (1 | 8453), destChainId (1 | 8453), token (key or OFT address), amount, INLINECODE27
• 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

1. 3. Create FxSdk once and reuse it.
2. Return SDK result first (routes/tx plan), then optionally provide transaction sending loop.
3. Keep nonce order from SDK-provided txs; send transactions sequentially. Wait for each tx receipt before sending the next.
4. After all txs are confirmed, wait at least one block before querying balances or positions — on-chain state may lag the receipt.
5. Validate inputs and surface SDK error messages directly when possible.
6. 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:

• - INLINECODE44
• INLINECODE45
• INLINECODE46

Canonical Imports

CODEBLOCK0

Use custom RPC only when provided:

CODEBLOCK1

Method Map

• - sdk.getPositions({ userAddress, market, type }): read-only; returns PositionInfo[] (positionId, rawColls, rawDebts, currentLeverage, lsdLeverage, rawCollsToken, rawDebtsToken, rawCollsDecimals, rawDebtsDecimals).
• INLINECODE49: open new position (positionId: 0) or add collateral/leverage.
• INLINECODE51: reduce or close (isClosePosition: true).
• INLINECODE53: rebalance leverage for existing position.
• INLINECODE54: long pool only.
• INLINECODE55: long pool only.
• INLINECODE56: fee quote for LayerZero V2 OFT bridge (Base <-> Ethereum). Use source chain RPC.
• INLINECODE57: 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.
• INLINECODE60: fxSAVE balance (shares wei, optional assets wei).
• INLINECODE61: pending redeem amount, cooldown, redeemableAt, isCooldownComplete.
• INLINECODE62: redeem status plus previewReceive (amountYieldOutWei, amountStableOutWei from previewRedeem — fxUSD + USDC to receive on claim).
• INLINECODE64: build claim tx when isCooldownComplete (uses claim(receiver)); execute txs in order.
• INLINECODE66: deposit USDC/fxUSD/basePool; returns { txs } (approve + deposit).
• INLINECODE68: 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)

• - depositAndMint / repayAndWithdraw (long only)

• - fxSAVE

Common Errors

• - "Input amount must be greater than 0" / "Amount to reduce must be greater than 0" → amount must be positive bigint.
• INLINECODE100 → slippage must be a number in (0, 100).
• INLINECODE102 → use valid 0x address or tokens.*.
• INLINECODE104 → caller must own positionId; verify with getPositions first.
• INLINECODE107 → 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. 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:

• - INLINECODE133
• INLINECODE134
• INLINECODE135
• INLINECODE136
• INLINECODE137
• INLINECODE138
• INLINECODE139
• INLINECODE140
• INLINECODE141
• INLINECODE142
• INLINECODE143
• INLINECODE144 (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
• INLINECODE146 — request templates for all methods, minimal snippets, validation checklist
• INLINECODE147 — typed FxAction adapter and sample payloads