> For the complete documentation index, see [llms.txt](https://docs.frankencoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frankencoin.com/api-docs/positions.md).

# Positions API

The Positions API provides comprehensive access to all collateralized lending positions in the Frankencoin ecosystem. Positions represent borrowing contracts where users lock collateral to mint ZCHF stablecoins.

## Overview

A **position** is a smart contract that holds collateral and allows the owner to mint ZCHF against it. The Positions API enables you to:

* Query all positions and their current state
* Filter positions by status (open, closed, pending)
* Track position ownership and transfers
* Monitor minting activity and history
* Analyze owner debt and fee payments over time

## Key Concepts

### Position Types

* **Original Positions**: Newly proposed positions that undergo a voting period before activation
* **Clone Positions**: Fast-tracked positions based on existing approved collateral types
* **Version 1 vs Version 2**: The protocol has evolved, with V2 positions including additional risk parameters

### Position States

* **Open**: Active positions available for minting
* **Closed**: Positions that have been terminated
* **Denied**: Positions rejected during the voting period
* **Pending**: Newly requested positions awaiting approval (typically within 5 days of creation)

### Minting Updates

Every time a position is adjusted (minting, burning, collateral changes, price adjustments), a **minting update** event is recorded. These provide a complete audit trail of position activity.

## Main Endpoints

### Position Queries

* `GET /positions/list` - Retrieve all positions with complete details
* `GET /positions/mapping` - Get positions as an address-keyed object for efficient lookup
* `GET /positions/open` - Filter for only active, open positions
* `GET /positions/requests` - View recently requested positions awaiting approval
* `GET /positions/owners` - Group positions by owner address

### Minting History

* `GET /positions/mintingupdates/list` - Get latest minting update events across all positions
* `GET /positions/mintingupdates/mapping` - Map minting updates by position address
* `GET /positions/mintingupdates/position/:version/:address` - Get history for a specific position
* `GET /positions/mintingupdates/owner/:address` - Get all minting activity for an owner

### Owner Analytics

* `GET /positions/owner/:address/fees` - Track fee payments over time
* `GET /positions/owner/:address/debt` - View historical debt evolution
* `GET /positions/owner/:address/history` - See which positions were owned when
* `GET /positions/owner/:address/transfers` - Monitor position ownership transfers

## Use Cases

### Portfolio Monitoring

Track all positions owned by a specific address to monitor collateralization ratios, debt levels, and fees paid:

```
GET /positions/mintingupdates/owner/0x963eC454423CD543dB08bc38fC7B3036B425b301
```

### Position Discovery

Find positions available for cloning by filtering for open original positions with specific collateral types:

```
GET /positions/open
```

### Risk Analysis

Monitor newly requested positions to assess protocol risk and participate in governance:

```
GET /positions/requests
```

### Historical Analysis

Track how a position has evolved over time by reviewing all minting updates:

```
GET /positions/mintingupdates/position/2/0x826C54287c0C1E2A4D0fbF81E2e734c85C48d3f4
```

## Data Structure

### Position Object

Each position includes:

* **Identification**: position address, version, owner
* **Collateral Details**: collateral token, balance, decimals, name, symbol
* **Minting Parameters**: limits, available capacity, amount minted, interest rate, fees
* **Status Flags**: isOriginal, isClone, denied, closed
* **Timestamps**: creation, start, cooldown, expiration, challenge period

### Minting Update Object

Each update event contains:

* **Position Info**: position address, owner, collateral details
* **Adjustment Data**: size changed, price adjusted, amount minted/burned
* **Fee Information**: fees paid, timeframe, annual interest rate
* **Metadata**: transaction hash, timestamp, version

## Notes

* All amounts are represented as strings in wei (1e18 for 18-decimal tokens)
* Interest rates are in PPM (parts per million): 20000 PPM = 2% annual
* The API returns up to 1000 most recent records for minting updates and historical queries
* Position addresses are unique identifiers and can be used across endpoints