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
get
/health
200

Service is healthy

Create login nonce for wallet authentication

post
/auth/nonce

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

Flow:

  1. Call this endpoint with your wallet address

  2. Receive a nonce and message to sign

  3. Sign the message with your wallet

  4. 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
post
/auth/nonce

Login with wallet signature

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
post
/auth/login

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
get
/auth/api-keys

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
post
/auth/api-keys

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
delete
/auth/api-keys/{key_id}

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
get
/api/staking/{protocol}/metrics

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
get
/api/staking/{protocol}/metadata
200

Protocol metadata

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
get
/api/staking/positions/{wallet}

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
get
/api/staking/positions/{wallet}/history
200

Staking history

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
get
/api/staking/positions/{wallet}/summary
200

Staking summary

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
post
/staking/{protocol}/stake

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
post
/staking/{protocol}/preview

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
get
/api/margin/positions/{address}

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
get
/api/margin/health/{address}

Sync positions from blockchain

post
/api/margin/sync/{address}

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

Process:

  1. Queries all lending protocols on-chain

  2. Fetches oracle prices

  3. Calculates health metrics

  4. 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
post
/api/margin/sync/{address}

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
get
/api/margin/markets

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
get
/api/margin/markets/{protocol}

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
get
/api/margin/markets/{protocol}/history

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
post
/api/margin/markets/{protocol}/simulate

List supported protocol adapters

get
/protocols

Returns metadata for all registered protocol adapters grouped by chain.

Responses
200

Protocol metadata

application/json
get
/protocols
200

Protocol metadata

Discovery service status

get
/protocols/discovery

Returns adapter discovery statistics and configuration health.

Responses
200

Discovery status

application/json
get
/protocols/discovery
200

Discovery status

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
get
/balances
200

Balance snapshot

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
get
/balances/{account}

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
get
/ws
No content
PreviousSupported Protocols

Last updated