FX SDK Agent Skill
Use this skill to produce reliable fx-sdk integrations for agent workflows.
Follow This Workflow
- 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).
- 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
- Create
FxSdk once and reuse it.
- Return SDK result first (routes/tx plan), then optionally provide transaction sending loop.
- Keep nonce order from SDK-provided
txs; send transactions sequentially. Wait for each tx receipt before sending the next.
- After all txs are confirmed, wait at least one block before querying balances or positions — on-chain state may lag the receipt.
- Validate inputs and surface SDK error messages directly when possible.
- 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.mdREADME.mdagent-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
| Token | Ethereum | Base |
|---|
| fxUSD | 0x085780639CC2cACd35E474e71f4d000e2405d8f6 | 0x55380fe7A1910dFf29A47B622057ab4139DA42C5 |
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:
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:
- A minimal adapter function with typed input.
- A safe dry-run mode (
planOnly) that returns SDK routes without sending transactions.
- A transaction executor function that consumes one selected route/result and sends
txs in nonce order.
- A post-execution step that waits ≥1 block then queries updated balance/positions to confirm the result.
- 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.tsexample/reduce-position.tsexample/adjust-position-leverage.tsexample/deposit-and-mint.tsexample/repay-and-withdraw.tsexample/get-positions.tsexample/layerzero-bridge.tsexample/get-fxsave-balance.tsexample/get-fxsave-config.tsexample/fxsave-deposit.tsexample/fxsave-withdraw.tsexample/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 eachreferences/sdk-playbook.md — request templates for all methods, minimal snippets, validation checklistreferences/agent-adapter-example.ts — typed FxAction adapter and sample payloads
