assetx/webapp-back/lending/README.md

Lending API Implementation

Overview

This directory contains the backend implementation for the AssetX Lending Market system.

API Endpoints

Query Endpoints (Public)

Get User Position

GET /api/lending/position/:address

Returns user's lending position including:

• Supplied USDC balance
• Borrowed USDC balance
• Collateral balances (YT-A, YT-B, YT-C)
• Health Factor
• LTV (Loan-to-Value) ratio
• Supply/Borrow APY

Response:

{
  "success": true,
  "data": {
    "user_address": "0x...",
    "wallet_address": "0x...",
    "supplied_balance": "10000.00",
    "supplied_balance_usd": 10000.00,
    "borrowed_balance": "1000.00",
    "borrowed_balance_usd": 1000.00,
    "collateral_balances": {
      "YT-A": {
        "token_symbol": "YT-A",
        "balance": "1000.00",
        "balance_usd": 2000000.00,
        "collateral_value": 1400000.00
      }
    },
    "health_factor": 14.0,
    "ltv": 10.0,
    "supply_apy": 6.1,
    "borrow_apy": 9.1
  }
}

Get Lending Stats

GET /api/lending/stats

Returns lending market statistics:

• Total supplied/borrowed USD
• Total collateral USD
• Utilization rate
• Average APYs
• User counts
• Total TVL

Response:

{
  "success": true,
  "data": {
    "total_supplied_usd": 50000000.00,
    "total_borrowed_usd": 30000000.00,
    "total_collateral_usd": 80000000.00,
    "utilization_rate": 60.0,
    "avg_supply_apy": 6.1,
    "avg_borrow_apy": 9.1,
    "total_users": 1250,
    "active_borrowers": 450,
    "total_tvl": 130000000.00
  }
}

Get Lending Markets

GET /api/lending/markets

Returns lending market configuration from lending_markets table.

Get All Tokens Info

GET /api/lending/tokens

Returns information about all supported tokens (USDC + YT tokens from assets table).

Response:

{
  "success": true,
  "data": {
    "stablecoins": [
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "contract_address_arb": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "contract_address_bsc": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
      }
    ],
    "yt_tokens": [
      {
        "symbol": "YT-A",
        "name": "YT-A",
        "decimals": 18,
        "contract_address_arb": "0x...",
        "contract_address_bsc": "0x...",
        "asset_code": "YT-A"
      }
    ]
  }
}

Get Token Info

GET /api/lending/tokens/:assetCode

Returns information about a specific token (USDC or YT-A/YT-B/YT-C).

Transaction Endpoints

Supply USDC

POST /api/lending/supply
Content-Type: application/json

{
  "amount": "1000.00",
  "tx_hash": "0x..."
}

Withdraw USDC

POST /api/lending/withdraw
Content-Type: application/json

{
  "amount": "500.00",
  "tx_hash": "0x..."
}

Supply Collateral

POST /api/lending/supply-collateral
Content-Type: application/json

{
  "asset": "YT-A",
  "amount": "100.00",
  "tx_hash": "0x..."
}

Withdraw Collateral

POST /api/lending/withdraw-collateral
Content-Type: application/json

{
  "asset": "YT-A",
  "amount": "50.00",
  "tx_hash": "0x..."
}

Borrow USDC

POST /api/lending/borrow
Content-Type: application/json

{
  "amount": "1000.00",
  "tx_hash": "0x..."
}

Repay USDC

POST /api/lending/repay
Content-Type: application/json

{
  "amount": "500.00",
  "tx_hash": "0x..."
}

Files

• models.go - Data models and request/response structures
• handlers.go - HTTP request handlers
• helpers.go - Helper functions (token info, calculations, validation)
• tokens.go - Token information endpoints
• routers.go - Route documentation (routes registered in main.go)
• README.md - This file

Current Implementation Status

✅ Completed

• API endpoint structure
• Request/response models
• Basic validation
• Mock data responses
• Database integration for token information
• USDC configuration (hardcoded as per frontend)
• YT token information from assets table
• Token validation against database
• Health factor and LTV calculation formulas
• Token info query endpoints

⏳ TODO

1. Blockchain Integration

   • Connect to smart contracts
   • Verify transactions on-chain
   • Query real-time balances
   • Calculate health factor from chain data

2. Database Integration

   • Store transaction records
   • Update lending_markets table
   • Track user positions
   • Generate statistics

3. Authentication

   • Add wallet signature verification
   • Implement user session management

4. Business Logic

   • Interest accrual calculations
   • Health factor monitoring
   • Liquidation logic
   • APY calculations

Database Schema

The lending system uses the following tables from database-schema-v1.1-final.sql:

• lending_markets - Lending market configuration
• transactions - Transaction records
• protocol_stats - Protocol-level statistics

Note: User position data is primarily read from blockchain, with caching in database.

Integration with Frontend

Frontend components that use these APIs:

• /lending/supply/SupplyPanel.tsx - Supply USDC
• /lending/supply/WithdrawPanel.tsx - Withdraw USDC
• /lending/repay/RepayBorrowDebt.tsx - Borrow/Repay USDC
• /lending/repay/RepaySupplyCollateral.tsx - Supply/Withdraw Collateral
• /lending/BorrowMarket.tsx - Display lending positions

Testing

# Start the server
go run main.go

# Test endpoints
curl http://localhost:8080/api/lending/stats
curl http://localhost:8080/api/lending/position/0x1234...

# Test transactions (requires auth)
curl -X POST http://localhost:8080/api/lending/supply \
  -H "Content-Type: application/json" \
  -d '{"amount": "1000", "tx_hash": "0x..."}'

Next Steps

1. Implement blockchain RPC integration
2. Add real transaction verification
3. Implement health factor calculations
4. Add liquidation monitoring
5. Integrate with frontend
6. Add comprehensive tests
7. Deploy to testnet