Seitrace Yield Provider API Integration Documentation
Version: 1.0
Date: 2025-04-22
Objective
To allow Seitrace to accurately display yield-generating opportunities (like staking pools, liquidity pools, vaults, lending markets, etc.) offered by your platform on the Sei blockchain. This requires Providers to expose a standardized API endpoint returning data about their available pools/opportunities.
Audience
This document is intended for the technical teams of Yield Providers integrating with Seitrace.
Integration Overview
Integrating with Seitrace involves two primary components:
A Dynamic API Endpoint: An HTTP GET endpoint that Seitrace will call periodically to retrieve up-to-date information on your platform's yield pools and opportunities.
Static Provider Information: A set of descriptive details about your platform provided separately during the onboarding process.
Let's detail each component.
1. Dynamic Pool Data API (Required)
The base URL for all API requests is: https://example-library-api.com
Each Provider must supply Seitrace with a stable HTTP API endpoint URL.
Method:GET
URL Structure: This will be specific to each Provider (e.g., https://api.yourdomain.com/seitrace/pools). Please provide the exact URL to the Seitrace team during onboarding.
Authentication: Currently, no specific authentication headers are required. The endpoint should be publicly accessible or use standard mechanisms communicated during onboarding if necessary.
Request Headers: Seitrace will typically include standard headers like Accept: application/json.
Request Parameters: No specific query parameters are required by Seitrace for this endpoint at this time.
The API endpoint MUST return a JSON object adhering to the structure defined below.
Success Status Code:200 OK
Content-Type:application/json
1.1. Overall Response Structure (Response)
The top-level JSON object must contain a single key, data, which holds an array of IPoolInfo objects.
export type Response = {
data: IPoolInfo[]; // Array containing details for each pool/vault/opportunity
}
1.2. Pool Information (IPoolInfo)
Each object within the data array represents a single yield opportunity and must conform to the IPoolInfo structure.
type IPoolInfo = {
pool_type: PoolType; // Specify pool type
pool_name: string; // Clear, human-readable name of the pool/vault/strategy (e.g., "SEI/USDC", "wSEI").
pool_url: string; // Direct deep-link URL to the specific pool/vault page on the Provider's website.
pool_address: string | null; // Contract address of the pool/vault on the Sei blockchain. Provide `null` if not applicable (e.g., for delegated staking).
pool_image: string | null; // URL to an image/icon representing the pool (e.g., pair icons). `null` if not available.
total_apr: number; // The overall total Annual Percentage Rate (APR) for the pool, calculated by summing all base and incentive APRs. **Represent as a percentage value (e.g., 15.5 for 15.5%).**
total_apy: number | null; // The overall total Annual Percentage Yield (APY) if compounding is involved (auto-compounding or manual). **Represent as a percentage value (e.g., 16.7 for 16.7%).** Provide `null` if APY is not applicable or cannot be calculated.
deposit_tokens: IDepositToken[]; // An array detailing the token(s) users need to deposit into this pool. See section 2.3.
is_auto_compound: boolean | null; // Set to `true` if the rewards are automatically compounded back into the principal. Set to `false` if compounding is manual or not applicable. Provide `null` if unsure or not applicable.
aprs: IAPR[]; // An array detailing the breakdown of different APR sources (base vs incentives). See section 2.4.
fee: number | null; // Any performance fee, withdrawal fee, or deposit fee associated with the pool. **Represent as a percentage value (e.g., 5 for 5%).** Provide `null` if no fees apply. Clarify fee type with Seitrace team if ambiguous.
tvl: number; // Total Value Locked in the pool, denominated in **USD**.
lock_period: number | null; // If applicable, the lock-up period for staking/deposits in SECONDS (e.g., 86400 for a 1-day lock). Leave `null` if not applicable.
}
1.3. Deposit Token Information (IDepositToken)
Details about the tokens required for depositing into the pool.
type IDepositToken = {
address: string; // Contract address of the deposit token on Sei.
deposited_amount: number | null; // Total amount of THIS token currently deposited in the pool across all users. (e.g., 12064.41). Provide `null` if not available.
name: string | null; // Human-readable name (e.g., "Wrapped Ether"). Provide `null` if not readily available*.
symbol: string | null; // Ticker symbol (e.g., "WETH"). Provide `null` if not readily available*.
icon_url: string | null; // URL to the token's icon. Provide `null` if not available*.
decimals: number | null; // The token's decimal precision (e.g., 18). Crucial for correct value interpretation. Provide `null` if not readily available*.
coingecko_id: string | null; // The CoinGecko identifier for the token (e.g., "wrapped-ether"). Helps Seitrace fetch market data. Provide `null` if not available*.
min_deposit: number | null; // Minimum amount of this token required for a single deposit transaction. Provide `null` if no minimum.
max_deposit: number | null; // Maximum amount of this token allowed for a single deposit transaction. Provide `null` if no maximum.
};
1.4. Reward Breakdown (IRewardData)
Details the components contributing to the total APR.
enum RewardType {
BASE = 'base', // Yield generated directly from the pool's core activity (e.g., trading fees for LPs, protocal reward, yield bearing tokens).
INCENTIVE = 'incentive', // Additional rewards provided, often in a different token, to incentivize participation.
}
type IRewardData = {
reward_token: IRewardToken; // Details of the token being paid out as reward for this specific APR component. See section 2.5.
type: RewardType; // Must be either 'base' or 'incentive'.
apr: number | null; // The APR for this specific component. **Represent as a percentage value (e.g., 10.2 for 10.2%).** Provide `null` only if absolutely unavailable.
apy: number | null; // The APY for this specific component, *if applicable and calculable separately*. Often `null` as total APY is usually calculated at the pool level. **Represent as a percentage value.**
};
1.5. Reward Token Information (IRewardToken)
Details about the token being distributed as rewards for a specific APR component.
type IRewardToken = {
address: string; // Contract address of the reward token on Sei.
name: string | null; // Human-readable name (e.g., "Wrapped SEI"). Provide `null` if not readily available*.
symbol: string | null; // Ticker symbol (e.g., "WSEI"). Provide `null` if not readily available*.
icon_url: string | null; // URL to the token's icon. Provide `null` if not available*.
decimals: number | null; // The token's decimal precision. Provide `null` if not readily available*.
coingecko_id: string | null; // The CoinGecko identifier. Provide `null` if not available*.
};
Note on Token Info (name, symbol, icon_url, decimals, coingecko_id): While Seitrace may attempt to look up missing token information using the provided address, it is strongly recommended that Providers include this data directly in the API response for accuracy, performance, and correct display on Seitrace. Please provide null only if the information is genuinely unavailable from your systems.
In addition to this dynamic pool data API, Seitrace requires some static information about your platform (the Provider). This information is typically collected once during onboarding and updated manually as needed. Please be prepared to provide the following details to the Seitrace team:
2.1. Provider Information (ProviderInfo)
type ProviderInfo = {
provider_name: string; // Your official brand name (e.g., "Pit Finance").
provider_home_url: string; // URL of your project's main homepage (e.g., "<https://pit.finance>").
provider_base_url: string; // Base URL used to construct individual pool links if needed (e.g., "<https://pit.finance/vaults/>"). Often the `pool_url` provided in the API is sufficient.
provider_datasource_endpoint: string; // The functional API endpoint URL you created based on this documentation.
provider_logo: string; // URL to your project's official logo (preferably SVG or high-res PNG).
provider_description: string | null; // A brief description of your platform/service.
how_to_stake: string | null; // Simple, newline-separated (\\n) steps on how users typically stake/deposit on your platform.
how_to_unstake: string | null; // Simple, newline-separated (\\n) steps on how users typically unstake/withdraw on your platform.
}
2.2. Example Response
{
"provider_name": "Pit Finance",
"provider_home_url": "<https://pit.finance>",
"provider_base_url": "<https://pit.finance/vaults/>",
"provider_datasource_endpoint": "<https://pit.finance/daemon/v1/api/1329/vaults/all>",
"provider_logo": "<https://pit.finance/assets/packages/short-logo-light.png>",
"provider_description": null,
"how_to_stake": "Connect your wallet\\nSelect a vault\\nEnter the deposit amount\\nApprove the transaction\\nConfirm the deposit\\nMonitor your position",
"how_to_unstake": "Connect your wallet\\nNavigate to your vault position\\nSelect the amount to unstake\\nConfirm the withdrawal\\nReceive your assets"
}
Additional Guidelines
Data Freshness: The data provided via the API should be kept reasonably up-to-date. Aim for updates at least every 5-15 minutes if possible, especially for TVL and APR/APY figures which can change frequently. If data is less dynamic (e.g., delegated staking APRs), less frequent updates (e.g., hourly) may suffice. Please communicate your expected update frequency to Seitrace.
Accuracy: Ensure the APR, APY, TVL, and fee data accurately reflects the current state of the pool on your platform.
Completeness: Provide values for all fields where possible. Use null only when data is truly unavailable or not applicable. Accurate pool_url, pool_address, deposit_tokens.address, reward_token.address, total_apr, and tvl are particularly important.
Units: Remember to use percentage values for total_apr, total_apy, aprs.apr, aprs.apy, and fee. Use USD for tvl.
Error Handling: In case of internal errors preventing data retrieval, the endpoint should return an appropriate HTTP error code (e.g., 500 Internal Server Error) with a minimal JSON error message if possible, e.g., {"error": "Failed to retrieve pool data"}.