Skip to content

Instantly share code, notes, and snippets.

@patcito

patcito/ftusd-session-preview-guide.md

Created January 22, 2026 11:42
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save patcito/8423973c115487c7fa642b4657134eda to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save patcito/8423973c115487c7fa642b4657134eda to your computer and use it in GitHub Desktop.
Download ZIP
ftUSD Session & Preview API Guide for Frontend Developers
Raw
ftusd-session-preview-guide.md

ftUSD Session & Preview API Guide

This guide covers the ftUSD preview endpoints for simulating operations and session management endpoints for session key delegation.

Base URL

Production: https://api.flyingtulip.com (or your configured API URL)

Preview Endpoints

These endpoints allow you to preview mint/redeem/stake/unstake operations without requiring the user's wallet to be connected to a specific chain. Useful for multi-chain UIs.

1. Preview Mint

Preview how much ftUSD will be minted for a given collateral amount.

GET /ftusd/preview/mint?chainId={chainId}&collateralToken={tokenAddress}&amount={amount}

Parameters:

Name Type Required Default Description
chainId int No 1 Chain ID
collateralToken string Yes - Collateral token address (0x...)
amount string Yes - Collateral amount in wei (base-10 integer)

Response:

{
  "success": true,
  "chain_id": 1,
  "input": "1000000000",
  "output": "1000000000000000000"
}

2. Preview Redeem

Preview how much collateral will be received for a given ftUSD amount.

GET /ftusd/preview/redeem?chainId={chainId}&collateralToken={tokenAddress}&amount={amount}

Parameters:

Name Type Required Default Description
chainId int No 1 Chain ID
collateralToken string Yes - Collateral token address
amount string Yes - ftUSD amount to redeem in wei (base-10 integer)

Response:

{
  "success": true,
  "chain_id": 1,
  "input": "1000000000000000000",
  "output": "1000000000"
}

3. Preview Stake

Preview how many sftUSD shares will be received for staking ftUSD.

GET /ftusd/preview/stake?chainId={chainId}&amount={amount}

Parameters:

Name Type Required Default Description
chainId int No 1 Chain ID
amount string Yes - ftUSD amount to stake in wei (base-10 integer)

Response:

{
  "success": true,
  "chain_id": 1,
  "input": "1000000000000000000",
  "output": "950000000000000000"
}

4. Preview Unstake

Preview how much ftUSD will be received for redeeming sftUSD shares.

GET /ftusd/preview/unstake?chainId={chainId}&shares={shares}

Parameters:

Name Type Required Default Description
chainId int No 1 Chain ID
shares string Yes - sftUSD shares to redeem in wei (base-10 integer)

Response:

{
  "success": true,
  "chain_id": 1,
  "input": "950000000000000000",
  "output": "1000000000000000000"
}

Session Management Endpoints

These endpoints support session key delegation via the SessionManager contract.

1. Get Session

Retrieve session configuration by session ID.

GET /ftusd/sessions/{sessionId}?chainId={chainId}

Parameters:

Name Type Required Default Description
sessionId string (path) Yes - Session ID (0x + 64 hex chars)
chainId int (query) No 1 Chain ID

Response:

{
  "success": true,
  "chain_id": 1,
  "session_id": "0x1234...abcd",
  "session": {
    "owner": "0x...",
    "delegate": "0x...",
    "valid_after": 1705708800,
    "valid_until": 1706313600,
    "max_calls": 100,
    "max_fee_bps": 500
  }
}

2. Get Session Nonce

Get current nonce for a session (used for replay protection).

GET /ftusd/sessions/{sessionId}/nonce?chainId={chainId}

Response:

{
  "success": true,
  "chain_id": 1,
  "session_id": "0x1234...abcd",
  "nonce": "5"
}

3. Get Session Token Limits

Get token spending limits and usage for a session.

GET /ftusd/sessions/{sessionId}/limits/{token}?chainId={chainId}

Parameters:

Name Type Required Description
sessionId string (path) Yes Session ID (0x + 64 hex chars)
token string (path) Yes Token address
chainId int (query) No Chain ID (default 1)

Response:

{
  "success": true,
  "chain_id": 1,
  "session_id": "0x1234...abcd",
  "token": "0x...",
  "limit": "1000000000000000000000",
  "spent": "500000000000000000000",
  "remaining": "500000000000000000000"
}

4. Compute Session ID

Compute the session ID from owner, delegate, and salt.

POST /ftusd/sessions/compute-id?chainId={chainId}

Request Body:

{
  "owner": "0x...",
  "delegate": "0x...",
  "salt": "0x0000000000000000000000000000000000000000000000000000000000000001"
}

Response:

{
  "success": true,
  "chain_id": 1,
  "session_id": "0x1234...abcd"
}

5. Check Session Revoked

Check if a session has been revoked.

GET /ftusd/sessions/{sessionId}/revoked?chainId={chainId}

Response:

{
  "success": true,
  "chain_id": 1,
  "session_id": "0x1234...abcd",
  "revoked": false
}

Usage Examples

Preview Hooks (React)

import { useQuery } from '@tanstack/react-query';

export function useFtUSDMintPreview(
  chainId: number,
  collateralToken: string,
  amount: string
) {
  return useQuery({
    queryKey: ['ftusd-preview-mint', chainId, collateralToken, amount],
    queryFn: async () => {
      const res = await fetch(
        `${API_URL}/ftusd/preview/mint?chainId=${chainId}&collateralToken=${collateralToken}&amount=${amount}`
      );
      if (!res.ok) throw new Error('Failed to preview mint');
      return res.json();
    },
    enabled: !!collateralToken && !!amount && amount !== '0',
  });
}

export function useFtUSDStakePreview(chainId: number, amount: string) {
  return useQuery({
    queryKey: ['ftusd-preview-stake', chainId, amount],
    queryFn: async () => {
      const res = await fetch(
        `${API_URL}/ftusd/preview/stake?chainId=${chainId}&amount=${amount}`
      );
      if (!res.ok) throw new Error('Failed to preview stake');
      return res.json();
    },
    enabled: !!amount && amount !== '0',
  });
}

Session Hooks (React)

export function useSession(sessionId: string, chainId = 1) {
  return useQuery({
    queryKey: ['ftusd-session', sessionId, chainId],
    queryFn: async () => {
      const res = await fetch(
        `${API_URL}/ftusd/sessions/${sessionId}?chainId=${chainId}`
      );
      if (!res.ok) throw new Error('Failed to fetch session');
      return res.json();
    },
    enabled: !!sessionId,
  });
}

export function useSessionTokenLimits(
  sessionId: string,
  token: string,
  chainId = 1
) {
  return useQuery({
    queryKey: ['ftusd-session-limits', sessionId, token, chainId],
    queryFn: async () => {
      const res = await fetch(
        `${API_URL}/ftusd/sessions/${sessionId}/limits/${token}?chainId=${chainId}`
      );
      if (!res.ok) throw new Error('Failed to fetch limits');
      return res.json();
    },
    enabled: !!sessionId && !!token,
  });
}

Swagger Documentation

Full API documentation available at: /swagger/index.html

Notes

  • All amounts/shares are strings to preserve precision (wei values, base-10)
  • Session IDs must be valid 32-byte hex values (0x + 64 hex characters)
  • Preview endpoints call view functions on-chain - they don't require user signatures
  • Multi-chain: Use chainId parameter to query different networks without wallet switching
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment