Fx Sdk Agent

Use FX Protocol TypeScript SDK (fx-sdk) to query positions (getPositions returns PositionInfo[] with rawColls, rawDebts, rawCollsToken, rawDebtsToken, decima...

Security Scan

The skill's files, instructions, and requested capabilities are consistent with an agent that helps integrate and use the @aladdindao/fx-sdk for read-only queries and transaction planning on Ethereum/Base.

Purpose & Capability

Name, description, SKILL.md, README, and code examples all consistently describe producing fx-sdk integrations, building tx plans, and producing runnable adapters. The imports and examples reference the @aladdindao/fx-sdk package which is appropriate for the stated purpose.

Instruction Scope

SKILL.md and reference files stay on-topic: they describe SDK calls, parameter validation, tx ordering, and how to execute txs with a wallet. They do not instruct the agent to read unrelated system files or exfiltrate data. They do, however, assume a wallet client and optionally an RPC URL will be supplied by the user (see note below).

Install Mechanism

There is no install spec (instruction-only skill). No archives or download URLs are used by the skill itself, so nothing is written to disk by the skill package during install.

Credentials

The skill declares no required env vars, but examples reference common runtime values (e.g., process.env.RPC_URL) and the SDK requires an RPC endpoint and a wallet to send transactions. The skill does not declare RPC or key env vars nor request wallet/private-key handling explicitly — the agent should prompt the user for RPC_URL and wallet credentials when needed. No unrelated credentials are requested by the skill.

Persistence & Privilege

always:false and user-invocable:true. The skill does not request permanent system presence or modify other skill configs; autonomous invocation is allowed by platform default but not combined with other red flags here.

Assessment

This skill appears to do what it says: help produce fx-sdk integration code and transaction plans. Before installing, consider: (1) The skill expects you to provide an RPC URL and a wallet to execute transactions — it doesn't declare env vars for these, so be prepared to supply them or the agent will need to ask. (2) The skill will generate tx payloads and recommend sending them with your wallet; it does not itself hold or transmit private keys, so never paste private keys into a chat — use a secure wallet client or key-management system. (3) The runtime code imports @aladdindao/fx-sdk — verify you install the official package from the project or npm and review it before running. (4) Double-check token addresses, chain IDs, and all generated txs on a testnet before using mainnet funds. If you want the skill to perform on-chain sends automatically, require explicit, secure key management and understand the financial risks called out in the README.

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

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:

• 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