Treno API Docs

Analytics API Documentation

Interact with the Treno Analytics for real-time DeFi data, risk indicators, and more. This documentation provides guidance for making API requests, handling responses, and managing errors.

Terminology

Key Terms in Our DeFi Platform:

DeFi is often too complex. We use familiar financial terms to make it easier for users without a Web3 or blockchain background. The following terms are used in the documentation to describe the different components and services of the platform.

Platform:

The underlying blockchain infrastructure where DeFi services operate. For example: Ethereum.
Technical term is Blockchain or Network.

Provider:

DeFi services or providers that offer financial services. Examples include Uniswap, Aave, and Compound.
Technical term is dApp or Protocol.

Active Investment Position:

A specific investment you currently hold within a provider. This could be a lending position, a liquidity provision, or a staking position.
Technical term is Token Balance.

Investment Type:

The nature of your investment. This includes categories like Lending, Liquidity Provision, and Staking.

Financial Product:

Various types of tokens and cryptocurrencies you can invest in, such as Stablecoins or Gold-tokens.

Asset:

Individual cryptocurrencies or tokens.
Technical term is Token.

Portfolio:

Your collection of assets and active investment positions.

Technical term is Wallet. In our context, it refers to a collection of wallets or virtual wallets.

Position:

An asset that you hold in your portfolio. This includes any cryptocurrency or token that you own.
Technical term is Token Balance.

Authentication

All API requests require an API key. Add it to the `Authorization` header for authentication:

Method 1: Header Authorization

Typically used within applications.

Authorization: Bearer YOUR_API_KEY

Method 2: Query Parameter Authorization

Commonly used for single API calls, such as in widgets, Excel sheets, or when simply working with JSON. When making widgets publicly available, ensure that only read-only tokens are generated to prevent your limits from being consumed by others.

Additionally, you can restrict iframes to only be embedded on specific domains using the `X-Frame-Options` or `Content-Security-Policy` (CSP) headers.

GET /portfolios/{portfolioId}/transactions?authToken=YOUR_API_KEY

Retrieve your API key from the Dashboard.

API Endpoints

In the following, we demonstrate only the basic functionality of the API. The complete documentation is available as an OpenAPI specification in the members' section.

Success Response

Wallet Transactions

Retrieve all transactions for a given wallet address.

GET /portfolios/{portfolioId}/transactions
Headers:
Authorization: Bearer YOUR_API_KEY

Example Response:

{
  "status": "success",
  "data": [
    {
      "assetId": "usdc",
      "amount": "10.45",
      "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "date": "2024-05-28",
      "direction": "in",
      "feeValue": "0",
      "platform": "ethereum",
      "subtype": "transaction-in",
      "symbol": "USDC",
      "transactionId": "0x0",
      "type": "transfer"
    }
  ]
}

Partial Success Response

Portfolio Performance

Retrieve the performance of assets held within a portfolio.

GET /portfolios/{portfolioId}/performance
Headers:
Authorization: Bearer YOUR_API_KEY

Example Response:

{
  "status": "partial_success",
  "errors": {
    "level": "WARN",
    "event": "MultipleErrors",
    "error": "Multiple errors occured calculation portfolio performance.",
    "context": {
      "origin": "getPortfolioPerformance",
      "errors": [
        {
          "level": "WARN",
          "event": "NoPriceDataError",
          "error": "Could not retrieve the asset price for the given date.",
          "context": {
            "id": "unknown-coin",
            "origin": "getHistoricPriceById",
            "date": "2024-05-28"
          }
        }
      ]
    }
  },
  "data": {
    "value30dAgo": "50000",
    "change30d": "-3",
    "diff30d": "-1500",
    "value1dAgo": "48000",
    "change1d": "1.5",
    "diff1d": "720",
    "value1hAgo": "48200",
    "change1h": "0.4",
    "diff1h": "20",
    "currentValue": "48400"
  }
}

Caching

The API uses caching to enhance performance and reduce server load, with expiry times tailored to the data type and its required freshness.

How Caching Works

The API caches data with expiry times set dynamically based on the type of data and its update frequency. For example:

  • Frequently Updated Data: Data like portfolio balances or real-time market prices have short expiry times to ensure freshness.
  • Static Data: Data such as contract IDs or asset categories are cached for longer periods as they rarely change.

Custom Expiry Options

Expiry durations can be influenced by user tiers:

  • Pro Users: Shorter expiry times for higher real-time accuracy.
  • Enterprise Users: Option to disable caching entirely for the most up-to-date data on every request.

Retrieve your API key from the Dashboard.

Error Handling

The API returns various errors to assist in usage. For example, it also provides non-critical errors that can occur during processing.

Client Error Responses

401 Unauthorized

Your API key is missing or invalid. Ensure that your key is included in the `Authorization` header.

{
  "status": "error",
  "message": "Unauthorized - API key is missing or invalid"
}

429 Too Many Requests

You’ve exceeded your rate limit. You can upgrade your plan to increase the limit.

{
  "status": "error",
  "message": "Rate limit exceeded - upgrade your plan"
}

Server Error Responses

502 Bad Gateway

The API call fails due to issues within the call stack, where multiple steps are required to complete the request. A 502 error indicates that the request encountered critical errors and could not be completed. Errors of this nature should be reported to support.

{
  "status": "failure",
  "errors": {
    "level": "CRITICAL",
    "event": "ApiCallError",
    "error": "Data not found for the given contract address.",
    "context": {
      "origin": "getLendingMarkets"
    }
  }
}

Rate Limiting

API requests are limited based on your subscription tier:

  • Free Tier: Limitations on API calls may apply.
  • Pro Tier: Full access with higher reliability and performance.
  • Enterprise Tier: Custom limits based on usage with dedicated support.

Support

If something doesn't work as expected, you can reach out to us through the following channels:

  • Email: Contact us directly via email for assistance.
  • Discord: Join our Discord server where our team and the community are happy to help with general questions and troubleshooting.
  • GitHub Issues: If you encounter a bug, feel free to create an issue on GitHub, and our team will look into it.

For general questions, the community on Discord is always ready to assist, alongside our support team.

Frequently Asked Questions (FAQ)