API Reference

Note: The APIs are currently in closed alpha testing and not yet live. This reference is for partners to review and understand our development progress.

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

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-01-01T00:00:00.000Z"
  }
}

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-01-01T00:00:00.000Z",
      "last_used_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

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

key_idstring · uuidOptional

secretstringOptional

Store this securely - it won't be shown again

rolestringOptional

rate_limitintegerOptional

permissionsstring[]Optional

created_atstring · date-timeOptional

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-01-01T00:00:00.000Z"
}

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-01-01T00:00:00.000Z"
}

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-01-01T00:00:00.000Z"
    }
  ]
}

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-01-01T00:00:00.000Z"
    }
  ],
  "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-01-01T00:00:00.000Z",
      "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

No content

400

Invalid WebSocket upgrade request

get/ws

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

No content

PreviousSupported Protocols

Last updated 10 months ago

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