API Reference | TETRICS

Health check

get

/health

Returns service readiness information and adapter health status.

Responses

200

Service is healthy

application/json

statusstringOptionalExample: healthy

servicestringOptionalExample: tetrics-modernized-api

versionstringOptionalExample: 0.2.0

chains_supportedstring[]OptionalExample: ["ethereum","hyperliquid"]

protocols_discoveredintegerOptional

discovery_service_statusstringOptionalExample: active

get

/health

GET /health HTTP/1.1
Host: api.tetrics.io
Accept: */*

200

Service is healthy

{
  "status": "healthy",
  "service": "tetrics-modernized-api",
  "version": "0.2.0",
  "chains_supported": [
    "ethereum",
    "hyperliquid"
  ],
  "protocols_discovered": 1,
  "discovery_service_status": "active",
  "adapter_health": {
    "ANY_ADDITIONAL_PROPERTY": true
  }
}

Create login nonce for wallet authentication

post

/auth/nonce

Generates a unique nonce and signing message for wallet-based authentication.

Flow:

Call this endpoint with your wallet address
Receive a nonce and message to sign
Sign the message with your wallet
Submit signature to /auth/login

Data Source: PostgreSQL Expires: 5 minutes

Body

wallet_addressstringRequiredPattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Nonce created successfully

application/json

noncestringOptional

Unique nonce for this authentication attempt

messagestringOptional

Message to sign with wallet

expires_ininteger · int64Optional

Nonce expiration in seconds

400

Invalid wallet address format

post

/auth/nonce

POST /auth/nonce HTTP/1.1
Host: api.tetrics.io
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "wallet_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
}

{
  "nonce": "text",
  "message": "text",
  "expires_in": 1
}

post

/auth/login

Authenticates a user by verifying their wallet signature against the nonce. Returns a JWT token and API key for subsequent requests.

Security: ECDSA signature verification ensures only the wallet owner can authenticate.

Returns:

JWT bearer token (for session-based auth)
API key credentials (for programmatic access)

Body

wallet_addressstringRequired

noncestringRequired

signaturestringRequired

Hex-encoded ECDSA signature

Responses

200

Login successful

application/json

jwtstringOptional

JWT bearer token for session auth

400

Invalid request payload

401

Signature verification failed or nonce expired

post

/auth/login

POST /auth/login HTTP/1.1
Host: api.tetrics.io
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "wallet_address": "text",
  "nonce": "text",
  "signature": "text"
}

{
  "jwt": "text",
  "api_key": {
    "key_id": "123e4567-e89b-12d3-a456-426614174000",
    "secret": "text",
    "role": "text",
    "rate_limit": 1,
    "created_at": "2026-03-26T06:13:17.667Z"
  }
}

List user's API keys

get

/auth/api-keys

Returns all API keys associated with the authenticated user.

Note: Secrets are not returned. Only key metadata is shown.

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Responses

200

API keys retrieved

application/json

401

Unauthorized

get

/auth/api-keys

GET /auth/api-keys HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "keys": [
    {
      "key_id": "123e4567-e89b-12d3-a456-426614174000",
      "label": "text",
      "role": "text",
      "rate_limit": 1,
      "created_at": "2026-03-26T06:13:17.667Z",
      "last_used_at": "2026-03-26T06:13:17.667Z"
    }
  ]
}

Create new API key

post

/auth/api-keys

Creates a new API key with custom permissions and rate limits.

Use Cases:

Separate keys for different applications
Custom rate limits per use case
Role-based access control

Important: The secret is only returned once. Store it securely.

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Body

labelstring · nullableOptional

rolestring · nullableOptional

permissionsstring[] · nullableOptional

rate_limitinteger · nullableOptional

Responses

201

API key created

application/json

400

Invalid request

401

Unauthorized

post

/auth/api-keys

POST /auth/api-keys HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "label": "Trading Bot",
  "role": "trader",
  "permissions": [
    "read:analytics",
    "write:orders"
  ],
  "rate_limit": 120
}

{
  "key_id": "123e4567-e89b-12d3-a456-426614174000",
  "secret": "text",
  "role": "text",
  "rate_limit": 1,
  "permissions": [
    "text"
  ],
  "created_at": "2026-03-26T06:13:17.667Z"
}

Revoke an API key

delete

/auth/api-keys/{key_id}

Permanently revokes an API key. This action cannot be undone.

Use Cases:

Rotating compromised keys
Deactivating unused keys
Security best practices

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

key_idstring · uuidRequired

API key ID to revoke

Responses

200

API key revoked successfully

application/json

messagestringOptionalExample: API key revoked successfully

401

Unauthorized

404

API key not found

delete

/auth/api-keys/{key_id}

DELETE /auth/api-keys/{key_id} HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "message": "API key revoked successfully"
}

Get protocol-level staking metrics

get

/api/staking/{protocol}/metrics

Returns aggregated staking metrics for a protocol (APY, TVL, total stakers).

Scope: Protocol-wide (not user-specific) Data Source: Mixed (DeFiLlama API, protocol APIs, on-chain queries) Data Freshness: Cached (refreshed every 5-15 minutes)

Supported Protocols:

lido: Ethereum staking via Lido
wsteth: Wrapped stETH
morpho: Morpho lending protocol
hype-staking: HYPE staking for beHYPE
hyperlend: HyperLend protocol
felix: Felix CDP protocol
hyperbeat: HyperBeat meta vault

Use Cases: Protocol comparison, APY discovery, TVL monitoring

Path parameters

protocolstring · enumRequired

Protocol identifier

Possible values:

Responses

200

Protocol metrics

application/json

protocolstringOptional

apystringOptional

tvlstringOptional

total_stakersintegerOptional

updated_atstring · date-timeOptional

404

Protocol not found

get

/api/staking/{protocol}/metrics

GET /api/staking/{protocol}/metrics HTTP/1.1
Host: api.tetrics.io
Accept: */*

{
  "protocol": "text",
  "apy": "text",
  "tvl": "text",
  "total_stakers": 1,
  "updated_at": "2026-03-26T06:13:17.667Z"
}

Get protocol metadata and validation constraints

get

/api/staking/{protocol}/metadata

Returns protocol configuration including supported methods, parameter constraints, and gas estimates.

Data Source: JSON protocol configuration files Use Cases: Dynamic form generation, parameter validation, gas estimation

Path parameters

protocolstringRequired

Responses

200

Protocol metadata

application/json

protocolstringOptional

supported_methodsstring[]Optional

validation_constraintsobjectOptional

gas_estimatesobjectOptional

get

/api/staking/{protocol}/metadata

GET /api/staking/{protocol}/metadata HTTP/1.1
Host: api.tetrics.io
Accept: */*

200

Protocol metadata

{
  "protocol": "text",
  "supported_methods": [
    "text"
  ],
  "validation_constraints": {},
  "gas_estimates": {}
}

Get user staking positions (real-time on-chain)

get

/api/staking/positions/{wallet}

Returns current staking balances across all supported protocols by querying blockchain in real-time.

Position Type: Yield-bearing ERC20 tokens (stETH, wstETH, beHYPE, etc.) Data Source: On-chain (Ethereum/Hyperliquid RPC via PositionTracker) Data Freshness: Real-time blockchain query Chain Scope: Multi-chain (Ethereum + Hyperliquid)

Returns:

All non-zero token balances for staking protocols
Current USD values
Protocol metadata

Use Cases: Real-time portfolio tracking, yield monitoring, liquidity management

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

walletstringRequired

Wallet address

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Current staking positions

application/json

walletstringOptional

401

Unauthorized

get

/api/staking/positions/{wallet}

GET /api/staking/positions/{wallet} HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "wallet": "text",
  "positions": [
    {
      "protocol": "text",
      "chain": "text",
      "token": "text",
      "balance": "text",
      "value_usd": "text"
    }
  ]
}

Get staking transaction history

get

/api/staking/positions/{wallet}/history

Returns historical staking transactions (stakes, withdrawals) for the user.

Data Source: PostgreSQL (staking_position_history table) Data Freshness: Updated after each staking transaction

Use Cases: Transaction history, audit trails, rewards tracking

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

walletstringRequired

Query parameters

protocolstringOptional

Filter by protocol

limitintegerOptionalDefault: 50

Responses

200

Staking history

application/json

walletstringOptional

transactionsobject[]Optional

get

/api/staking/positions/{wallet}/history

GET /api/staking/positions/{wallet}/history HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

200

Staking history

{
  "wallet": "text",
  "transactions": [
    {}
  ]
}

Get aggregated staking summary

get

/api/staking/positions/{wallet}/summary

Returns aggregated staking statistics across all protocols for the user.

Data Source: Computed from on-chain positions Aggregations: Total staked value (USD), positions by protocol, positions by chain

Use Cases: Portfolio overview, total value calculation, protocol diversification analysis

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

walletstringRequired

Responses

200

Staking summary

application/json

walletstringOptional

total_staked_usdstringOptional

positions_by_protocolobjectOptional

positions_by_chainobjectOptional

get

/api/staking/positions/{wallet}/summary

GET /api/staking/positions/{wallet}/summary HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

200

Staking summary

{
  "wallet": "text",
  "total_staked_usd": "text",
  "positions_by_protocol": {},
  "positions_by_chain": {}
}

Execute staking transaction

post

/staking/{protocol}/stake

Executes a staking transaction (stake, unstake, withdraw, etc.) for the specified protocol.

Execution Modes:

direct: API executes transaction with its own wallet (testing/development)
broadcast: User provides signed transaction for broadcasting (production)

Supported Methods (vary by protocol):

deposit, stake: Stake tokens
withdraw, unstake: Withdraw staked tokens
wrap, unwrap: Convert between token forms (e.g., stETH ↔ wstETH)
supply, borrow, repay, redeem: Lending operations (Morpho, HyperLend)

Data Source: On-chain execution via protocol adapters Returns: Transaction receipt with gas used, output amounts

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

protocolstringRequired

Body

amountstringRequired

Amount in token units (wei for ETH)

assetstring · nullableOptional

methodstring · nullableOptional

recipientstring · nullableOptional

user_addressstring · nullableOptional

modestring · enum · nullableOptionalPossible values:

decimalsinteger · nullableOptional

signed_transactionstring · nullableOptional

For broadcast mode

Responses

200

Transaction executed

application/json

successbooleanOptional

tx_hashstring · nullableOptional

gas_usedstring · nullableOptional

output_amountstring · nullableOptional

errorstring · nullableOptional

400

Invalid parameters

422

Transaction failed

post

/staking/{protocol}/stake

POST /staking/{protocol}/stake HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "amount": "1000000000000000000",
  "method": "deposit",
  "mode": "direct"
}

{
  "success": true,
  "tx_hash": "text",
  "gas_used": "text",
  "output_amount": "text",
  "error": "text"
}

Preview staking action without executing

post

/staking/{protocol}/preview

Simulates a staking transaction to preview gas costs and output amounts without executing on-chain.

Use Cases: Gas estimation, parameter validation, dry-run testing

Returns:

Estimated gas cost
Expected output amount
Validation errors (if any)

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

protocolstringRequired

Body

amountstringRequired

Amount in token units (wei for ETH)

assetstring · nullableOptional

methodstring · nullableOptional

recipientstring · nullableOptional

user_addressstring · nullableOptional

modestring · enum · nullableOptionalPossible values:

decimalsinteger · nullableOptional

signed_transactionstring · nullableOptional

For broadcast mode

Responses

200

Preview result

application/json

estimated_gasstringOptional

expected_outputstringOptional

validation_errorsstring[]Optional

400

Invalid parameters

post

/staking/{protocol}/preview

POST /staking/{protocol}/preview HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 200

{
  "amount": "text",
  "asset": "text",
  "method": "text",
  "recipient": "text",
  "user_address": "text",
  "mode": "direct",
  "decimals": 1,
  "extra_params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "signed_transaction": "text"
}

{
  "estimated_gas": "text",
  "expected_output": "text",
  "validation_errors": [
    "text"
  ]
}

Get all margin positions (cross-chain)

get

/api/margin/positions/{address}

Returns unified view of all collateral and debt positions across lending protocols and chains.

Position Type: Collateral deposits and borrowed amounts Data Source: PostgreSQL (cross_chain_positions table) Data Freshness: Last sync timestamp (call /sync to update) Chain Scope: Cross-chain (Ethereum + Hyperliquid) Protocols: Morpho, HyperLend, Aave-like protocols

Returns:

All collateral positions
All debt positions
Grouped by chain and protocol
USD values and weighted amounts
Market overview and top exposures

Use Cases:

Unified portfolio view
Cross-protocol position tracking
Collateral diversification analysis

Important: Data is synced from blockchain. Call /api/margin/sync/:address to refresh.

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

addressstringRequired

Margin account address

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Margin positions

application/json

401

Unauthorized

404

Margin account not found

get

/api/margin/positions/{address}

GET /api/margin/positions/{address} HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "margin_account": {
    "address": "text",
    "total_collateral_usd": "text",
    "total_borrowed_usd": "text",
    "health_factor": "text"
  },
  "positions": [
    {
      "protocol": "text",
      "chain": "text",
      "asset": "text",
      "position_type": "collateral",
      "amount": "text",
      "value_usd": "text",
      "weighted_value_usd": "text"
    }
  ],
  "positions_by_chain": {
    "ANY_ADDITIONAL_PROPERTY": [
      {
        "protocol": "text",
        "chain": "text",
        "asset": "text",
        "position_type": "collateral",
        "amount": "text",
        "value_usd": "text",
        "weighted_value_usd": "text"
      }
    ]
  },
  "collateral_positions": [
    {
      "protocol": "text",
      "chain": "text",
      "asset": "text",
      "position_type": "collateral",
      "amount": "text",
      "value_usd": "text",
      "weighted_value_usd": "text"
    }
  ],
  "debt_positions": [
    {
      "protocol": "text",
      "chain": "text",
      "asset": "text",
      "position_type": "collateral",
      "amount": "text",
      "value_usd": "text",
      "weighted_value_usd": "text"
    }
  ]
}

Get comprehensive health metrics for liquidation risk

get

/api/margin/health/{address}

Returns detailed health factor analysis and liquidation risk metrics.

Data Source: PostgreSQL (health_snapshots table) Calculation: Weighted collateral / weighted debt with protocol-specific LTV ratios Data Freshness: Last sync timestamp

Metrics:

Health factor (>1.0 = safe, <1.0 = liquidatable)
Total collateral (USD)
Weighted collateral with LTV ratios
Total debt (USD)
Distance to liquidation (%)
Max borrowable amount
Risk level (healthy/warning/critical)

Use Cases:

Liquidation prevention
Risk monitoring alerts
Borrowing capacity calculation

Important: Call /api/margin/sync/:address first for up-to-date health metrics.

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

addressstringRequired

Responses

200

Health metrics

application/json

addressstringOptional

health_factorstring · nullableOptional

Greater than 1.0 = safe, less than 1.0 = liquidatable

risk_levelstring · enumOptionalPossible values:

total_collateral_usdstringOptional

weighted_collateral_usdstringOptional

total_debt_usdstringOptional

weighted_debt_usdstringOptional

liquidation_threshold_usdstringOptional

distance_to_liquidation_pctstringOptional

max_borrowable_usdstringOptional

401

Unauthorized

get

/api/margin/health/{address}

GET /api/margin/health/{address} HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "address": "text",
  "health_factor": "text",
  "risk_level": "healthy",
  "total_collateral_usd": "text",
  "weighted_collateral_usd": "text",
  "total_debt_usd": "text",
  "weighted_debt_usd": "text",
  "liquidation_threshold_usd": "text",
  "distance_to_liquidation_pct": "text",
  "max_borrowable_usd": "text"
}

Sync positions from blockchain

post

/api/margin/sync/{address}

Triggers synchronization of margin positions from on-chain state to database.

Process:

Queries all lending protocols on-chain
Fetches oracle prices
Calculates health metrics
Updates database with latest positions

Data Source: On-chain → PostgreSQL via PositionSyncService Duration: ~2-5 seconds Protocols Synced: All enabled lending protocols (optional filter)

Use Cases:

Before checking health factor
After executing positions on-chain
Scheduled background jobs

Returns: Sync job status with updated position counts

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

addressstringRequired

Body

protocolsstring[] · nullableOptional

Optional filter for specific protocols

Responses

200

Sync completed

application/json

addressstringOptional

synced_positionsintegerOptional

total_collateral_usdstringOptional

total_borrowed_usdstringOptional

job_idstringOptional

duration_msinteger · int64Optional

messagestringOptional

401

Unauthorized

422

Sync failed

post

/api/margin/sync/{address}

POST /api/margin/sync/{address} HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "protocols": [
    "morpho",
    "hyperlend"
  ]
}

{
  "address": "text",
  "synced_positions": 1,
  "total_collateral_usd": "text",
  "total_borrowed_usd": "text",
  "job_id": "text",
  "duration_ms": 1,
  "message": "text"
}

List lending markets with metrics and filtering

get

/api/margin/markets

Returns lending market metrics across all supported protocols with advanced filtering.

Scope: Protocol-wide market data (not user-specific) Data Source: PostgreSQL (market_metrics, market_protocol_metrics tables) Data Freshness: Background scheduler updates every 5-15 minutes

Metrics:

Total supply and borrow (USD)
Utilization rate
Supply APY and borrow APY
Oracle health status
Risk score
Market volatility

Filters:

protocol: Filter by protocol name
chain: Filter by chain
asset: Filter by asset symbol
market_type: lending/borrowing/vault
risk_min/risk_max: Filter by risk score

Use Cases:

Market opportunity discovery
Yield comparison across protocols
Risk-based market filtering

Note: This endpoint should ideally be at /api/markets (not /api/margin/markets).

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Query parameters

protocolstringOptional

chainstringOptional

assetstringOptional

market_typestring · enumOptionalPossible values:

risk_minstringOptional

risk_maxstringOptional

Responses

200

Market metrics

application/json

401

Unauthorized

get

/api/margin/markets

GET /api/margin/markets HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "protocol_metrics": [
    {
      "protocol": "text",
      "total_supply_usd": "text",
      "total_borrow_usd": "text",
      "average_utilization": "text"
    }
  ],
  "market_metrics": [
    {
      "market_id": "text",
      "protocol": "text",
      "chain": "text",
      "asset": "text",
      "total_supply": "text",
      "total_borrow": "text",
      "utilization_rate": "text",
      "supply_apy": "text",
      "borrow_apy": "text",
      "risk_score": "text",
      "updated_at": "2026-03-26T06:13:17.667Z"
    }
  ]
}

Get markets for specific protocol

get

/api/margin/markets/{protocol}

Returns all lending markets and aggregated protocol metrics for a single protocol.

Data Source: PostgreSQL Returns:

Individual market metrics
Protocol-level aggregates (total TVL, average utilization, etc.)

Use Cases: Protocol-specific analysis, deep-dive into single protocol

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

protocolstringRequired

Protocol identifier (e.g., "morpho", "hyperlend")

Responses

200

Protocol markets

application/json

protocolstringOptional

401

Unauthorized

404

Protocol not found

get

/api/margin/markets/{protocol}

GET /api/margin/markets/{protocol} HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "protocol": "text",
  "markets": [
    {
      "market_id": "text",
      "protocol": "text",
      "chain": "text",
      "asset": "text",
      "total_supply": "text",
      "total_borrow": "text",
      "utilization_rate": "text",
      "supply_apy": "text",
      "borrow_apy": "text",
      "risk_score": "text",
      "updated_at": "2026-03-26T06:13:17.667Z"
    }
  ],
  "aggregates": {
    "total_tvl": "text",
    "average_utilization": "text"
  }
}

Get market history for time-series analysis

get

/api/margin/markets/{protocol}/history

Returns historical snapshots of market metrics for trend analysis.

Data Source: PostgreSQL (market_metrics_history table) Granularity: Hourly or daily snapshots Time Range: Configurable via query parameters

Use Cases:

Utilization trend charts
APY history tracking
Market volatility analysis

Query Parameters:

market_id: Specific market identifier (required)
start_date: Start of time range
end_date: End of time range
limit: Max number of snapshots

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

protocolstringRequired

Query parameters

market_idstringRequired

start_datestring · date-timeOptional

end_datestring · date-timeOptional

limitintegerOptionalDefault: 100

Responses

200

Market history

application/json

market_idstringOptional

401

Unauthorized

get

/api/margin/markets/{protocol}/history

GET /api/margin/markets/{protocol}/history?market_id=text HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "market_id": "text",
  "history": [
    {
      "timestamp": "2026-03-26T06:13:17.667Z",
      "utilization_rate": "text",
      "supply_apy": "text",
      "borrow_apy": "text"
    }
  ]
}

Simulate market scenario (what-if analysis)

post

/api/margin/markets/{protocol}/simulate

Simulates the impact of a supply or borrow action on market metrics.

Simulation Logic:

Adds hypothetical supply/borrow to current market state
Recalculates utilization rate
Projects new APY based on utilization curve
Estimates new risk score

Use Cases:

What-if analysis before large positions
Optimal amount calculation
Market impact estimation

Inputs:

market_id: Target market
action: "supply" or "borrow"
amount: Amount to simulate (in token units)
stress_pct: Optional stress test % (default: 0)

Returns:

Projected supply and borrow amounts
Projected utilization rate
Projected risk score
Warnings if thresholds exceeded

Authorizations

AuthorizationstringRequired

API key authentication. Contact the Tetrics team to obtain your API key.

Format: Authorization: ApiKey <key_id>:<secret>

Example: Authorization: ApiKey 550e8400-e29b-41d4-a716-446655440000:your-secret-key

Path parameters

protocolstringRequired

Body

market_idstringRequired

actionstring · enumRequiredPossible values:

amountstringRequired

Amount in token units

stress_pctnumber · nullableOptional

Stress test percentage (default 0)

Responses

200

Simulation result

application/json

protocolstringOptional

market_idstringOptional

actionstringOptional

amountstringOptional

projected_supplystringOptional

projected_borrowstringOptional

projected_utilization_pctstringOptional

projected_riskstringOptional

notesstring[]Optional

400

Invalid simulation parameters

401

Unauthorized

post

/api/margin/markets/{protocol}/simulate

POST /api/margin/markets/{protocol}/simulate HTTP/1.1
Host: api.tetrics.io
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "market_id": "morpho-wsteth-usdc",
  "action": "borrow",
  "amount": "10000000000",
  "stress_pct": 10
}

{
  "protocol": "text",
  "market_id": "text",
  "action": "text",
  "amount": "text",
  "projected_supply": "text",
  "projected_borrow": "text",
  "projected_utilization_pct": "text",
  "projected_risk": "text",
  "notes": [
    "text"
  ]
}

List supported protocol adapters

get

/protocols

Returns metadata for all registered protocol adapters grouped by chain.

Responses

200

Protocol metadata

application/json

total_protocolsintegerOptional

get

/protocols

GET /protocols HTTP/1.1
Host: api.tetrics.io
Accept: */*

200

Protocol metadata

{
  "protocols": [
    {
      "name": "text",
      "chain": "text",
      "version": "text",
      "description": "text",
      "supported_methods": [
        "text"
      ],
      "contract_address": "text",
      "requires_approval": true
    }
  ],
  "protocols_by_chain": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "total_protocols": 1
}

Discovery service status

get

/protocols/discovery

Returns adapter discovery statistics and configuration health.

Responses

200

Discovery status

application/json

total_protocols_discoveredintegerOptional

total_protocols_enabledintegerOptional

last_config_reloadinteger · int64 · nullableOptional

get

/protocols/discovery

GET /protocols/discovery HTTP/1.1
Host: api.tetrics.io
Accept: */*

200

Discovery status

{
  "total_protocols_discovered": 1,
  "total_protocols_enabled": 1,
  "protocols_by_chain": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "health_status": {
    "ANY_ADDITIONAL_PROPERTY": true
  },
  "discovery_stats": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "last_config_reload": 1
}

Get balances for default account

get

/balances

Returns a balance snapshot for the default account used in automated tests.

Responses

200

Balance snapshot

application/json

accountstringOptionalExample: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266

get

/balances

GET /balances HTTP/1.1
Host: api.tetrics.io
Accept: */*

200

Balance snapshot

{
  "account": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "balances_by_chain": {
    "ANY_ADDITIONAL_PROPERTY": {
      "native_token": "text",
      "tokens": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  }
}

Get balances for a wallet

get

/balances/{account}

Returns ETH and token balances for the provided wallet across all supported chains.

Path parameters

accountstringRequired

Wallet address (0x-prefixed)

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Balance snapshot

application/json

accountstringOptionalExample: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266

400

Invalid account address supplied

get

/balances/{account}

GET /balances/{account} HTTP/1.1
Host: api.tetrics.io
Accept: */*

{
  "account": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "balances_by_chain": {
    "ANY_ADDITIONAL_PROPERTY": {
      "native_token": "text",
      "tokens": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  }
}

WebSocket connection for real-time updates

get

/ws

Establishes a WebSocket connection for streaming real-time strategy execution updates, transaction receipts, and balance changes.

Message Types:

strategy_progress - Step-by-step execution updates
transaction_update - Transaction confirmation events
balance_update - Wallet balance changes
error - Execution errors and warnings

Example Message:

{
  "type": "strategy_progress",
  "data": {
    "execution_id": "abc-123",
    "step": 2,
    "total_steps": 5,
    "protocol": "lido",
    "status": "completed"
  }
}

Responses

101

WebSocket connection established

400

Invalid WebSocket upgrade request

get

/ws

GET /ws HTTP/1.1
Host: api.tetrics.io
Accept: */*

No content

hashtagHealth check

hashtagCreate login nonce for wallet authentication

hashtagLogin with wallet signature

hashtagList user's API keys

hashtagCreate new API key

hashtagRevoke an API key

hashtagGet protocol-level staking metrics

hashtagGet protocol metadata and validation constraints

hashtagGet user staking positions (real-time on-chain)

hashtagGet staking transaction history

hashtagGet aggregated staking summary

hashtagExecute staking transaction

hashtagPreview staking action without executing

hashtagGet all margin positions (cross-chain)

hashtagGet comprehensive health metrics for liquidation risk

hashtagSync positions from blockchain

hashtagList lending markets with metrics and filtering

hashtagGet markets for specific protocol

hashtagGet market history for time-series analysis

hashtagSimulate market scenario (what-if analysis)

hashtagList supported protocol adapters

hashtagDiscovery service status

hashtagGet balances for default account

hashtagGet balances for a wallet

hashtagWebSocket connection for real-time updates

Health check

Create login nonce for wallet authentication

Login with wallet signature

List user's API keys

Create new API key

Revoke an API key

Get protocol-level staking metrics

Get protocol metadata and validation constraints

Get user staking positions (real-time on-chain)

Get staking transaction history

Get aggregated staking summary

Execute staking transaction

Preview staking action without executing

Get all margin positions (cross-chain)

Get comprehensive health metrics for liquidation risk

Sync positions from blockchain

List lending markets with metrics and filtering

Get markets for specific protocol

Get market history for time-series analysis

Simulate market scenario (what-if analysis)

List supported protocol adapters

Discovery service status

Get balances for default account

Get balances for a wallet

WebSocket connection for real-time updates