# Prices API The Prices API provides access to current and historical price data for all collateral assets in the Frankencoin ecosystem, as well as system-wide collateralization ratios. This is essential for monitoring position health, calculating liquidation thresholds, and displaying accurate financial information. ## Overview The Prices API enables you to: * Query current prices for all collateral tokens * Access historical price data for charting and analysis * Monitor collateralization ratios across the ecosystem * Track price feeds for specific collateral assets * Analyze price trends over time ## Key Concepts ### Price Sources Prices in the Frankencoin ecosystem come from: * On-chain oracles (Chainlink, Uniswap TWAP, etc.) * Position-specific price feeds set during creation * Aggregated market data All prices are denominated in CHF (Swiss Francs) or ZCHF. ### Collateralization Ratios Two key ratios track ecosystem health: * **Ratio by Free Float**: Collateral value / circulating ZCHF supply * **Ratio by Total Supply**: Collateral value / total ZCHF supply These ratios indicate how well-backed the ZCHF stablecoin is by collateral. ## Main Endpoints ### Prices Controller #### Current Prices * `GET /prices/ticker/:ticker` - Get price for a specific ticker symbol (e.g., WBTC, WETH, FPS) * `GET /prices/list` - Get all token prices with metadata * `GET /prices/mapping` - Get prices as address-keyed mapping for efficient lookup #### Token Information * `GET /prices/erc20/mint` - Get Frankencoin (ZCHF) token information * `GET /prices/erc20/fps` - Get FPS token information * `GET /prices/erc20/collateral` - Get all collateral token information #### Owner Analytics * `GET /prices/owner/:address/valueLocked` - Get historical time series of total value locked by owner #### Market Data * `GET /prices/marketChart` - Get Frankencoin market chart data from CoinGecko (prices, market caps, volumes) ### Prices History Controller #### Price History * `GET /prices/history/list` - Complete price history for all collateral types with CHF prices * `GET /prices/history/:address` - Price history for a specific collateral token The history endpoint for a specific token returns: * Token metadata (name, symbol, decimals, address) * Current price in CHF * Historical prices as a time-series (timestamp → CHF price mapping) #### Collateralization Ratios * `GET /prices/history/ratio` - Historical collateralization ratio data Returns: * Current timestamp * `collateralRatioByFreeFloat`: Time series of ratios based on circulating supply * `collateralRatioBySupply`: Time series of ratios based on total supply ## Use Cases ### Position Health Monitoring Fetch current prices to calculate if positions are adequately collateralized: ``` GET /prices/list ``` Then compare position collateral value against minted amount. ### Quick Price Lookup by Ticker Get the price of a specific token by its symbol: ``` GET /prices/ticker/WBTC ``` Returns price in USD and CHF for WBTC. ### Price Charts Build historical price charts for collateral assets: ``` GET /prices/history/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599 ``` This returns WBTC price history that can be charted over time. ### System Health Dashboard Monitor ecosystem-wide collateralization: ``` GET /prices/history/ratio ``` Display ratios over time to show protocol health trends. ### Liquidation Alerts Compare current prices against position liquidation thresholds to alert users of risks: 1. Get current prices: `GET /prices/list` 2. Fetch user's positions: `GET /positions/owner/:address` 3. Calculate collateralization ratios 4. Alert if approaching liquidation levels ### Multi-Asset Analysis Compare price performance across different collateral types: ``` GET /prices/history/list ``` Analyze which collateral types are most stable or volatile. ### Token Metadata Lookup Get ERC20 information for system tokens: ``` GET /prices/erc20/mint # ZCHF token info GET /prices/erc20/fps # FPS token info GET /prices/erc20/collateral # All collateral tokens ``` ### Owner Value Tracking Track historical value locked by a specific owner across all their positions: ``` GET /prices/owner/0x963eC454423CD543dB08bc38fC7B3036B425b301/valueLocked ``` Returns yearly time series of total collateral value. ### Market Data Integration Fetch CoinGecko market data for Frankencoin: ``` GET /prices/marketChart ``` Returns prices, market caps, and trading volumes over time. ## Data Structure ### Price List Response Array of price objects with metadata: ```json [ { "address": "0x1bA26788dfDe592fec8bcB0Eaff472a42BE341B2", "name": "Frankencoin Pool Share", "symbol": "FPS", "decimals": 18, "timestamp": 1768915146172, "price": { "usd": 1555.45, "chf": 1234.49 } } ] ``` ### Price Mapping Response Object mapping addresses to price data: ```json { "0x1ba26788dfde592fec8bcb0eaff472a42be341b2": { "address": "0x1bA26788dfDe592fec8bcB0Eaff472a42BE341B2", "name": "Frankencoin Pool Share", "symbol": "FPS", "decimals": 18, "timestamp": 1768915146172, "price": { "usd": 1555.45, "chf": 1234.49 } } } ``` ### Historical Price Response (Specific Token) ```json { "address": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", "name": "Wrapped BTC", "symbol": "WBTC", "decimals": 8, "timestamp": 1768964400003, "price": { "chf": 70374.6 }, "history": { "1759158000005": 90567.46, "1759161600002": 91163.2, ... } } ``` ### Collateralization Ratio Response ```json { "timestamp": 1768964400003, "collateralRatioByFreeFloat": { "1759158000005": 3.138139819821414, "1759161600002": 3.142567234521876, ... }, "collateralRatioBySupply": { "1759158000005": 1.688283955398297, "1759161600002": 1.689342187654321, ... } } ``` ## Understanding Collateral Ratios ### Healthy Ranges * **Above 1.5**: System is overcollateralized, very healthy * **1.2 - 1.5**: Normal operating range * **1.0 - 1.2**: Warning zone, increased risk * **Below 1.0**: Critical, system is undercollateralized ### Free Float vs Total Supply * **By Free Float**: More conservative, only counts circulating ZCHF * **By Supply**: Includes all ZCHF, even locked or uncirculated The free float ratio is typically higher (more conservative) than the total supply ratio. ## Notes ### Timestamps * Historical data uses Unix millisecond timestamps as keys * The main `timestamp` field indicates when data was last updated ### Price Precision * Prices are in CHF with decimal precision * Historical endpoints may have varying time intervals between data points ### Performance Considerations * Price history objects can be large (hundreds of data points) * Consider caching price data with appropriate TTLs (1-5 minutes for current prices, longer for historical) * For charting, you may want to downsample historical data client-side ### Integration Best Practices 1. **Poll Current Prices**: Update every 1-5 minutes for position monitoring 2. **Cache Historical Data**: Price history changes infrequently, cache for 15-30 minutes 3. **Handle Missing Data**: Not all timestamps will have data, interpolate when necessary for charts 4. **Monitor Ratios**: Set up alerts when collateralization ratios drop below thresholds 5. **Validate Addresses**: Always validate collateral addresses against the Collateral API before using prices ## Example: Building a Position Monitor ```javascript // 1. Get current prices const pricesData = await fetch('https://api.frankencoin.com/prices/mapping').then(r => r.json()); // 2. Get user positions const positions = await fetch(`https://api.frankencoin.com/positions/owners`).then(r => r.json()); const userPositions = positions.map[address] || []; // 3. Calculate health for each position userPositions.forEach(position => { const priceInfo = pricesData[position.collateral.toLowerCase()]; const collateralPrice = priceInfo.price.usd; const collateralValue = (position.collateralBalance / Math.pow(10, position.collateralDecimals)) * collateralPrice; const mintedValue = position.minted / 1e18; const ratio = collateralValue / mintedValue; if (ratio < 1.2) { console.warn(`Position ${position.position} is at risk! Ratio: ${ratio.toFixed(2)}`); } }); ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.frankencoin.com/api-docs/prices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.