API Documentation

Integrate Maya Tracker data into your own applications. Access real-time and historical data for CACAO liquidity pools and Maya Protocol analytics.

Authentication Required

All API requests require a valid API Key. Keys are currently issued manually by the administrator.

Base URL

https://api.cacaotracker.xyz

Get an API Key

Contact me to request an API key for your project.

Twitter / X

DM @toed_i

Discord

Message directly

@toedi_

Authentication

Include your API key in the header of every request.

Headerx-api-key

Example Request

curl -H "x-api-key: YOUR_API_KEY" https://api.cacaotracker.xyz/history/maya...

Endpoints

GET/history/:address

Returns historical position data for a specific Maya address.

Path Parameters

Name	Type	Description
address	string	The Maya Protocol address (starts with `maya...`)

Response

200 OK

{

"history":[

{

"time": 1715000000000,

"value": 5234.5,

"units": 12500000000,

"price": 0.85

}

"current":{

"time": 1715000000000,

"value": 5234.5,

"units": 12500000000,

"price": 0.85

}

GET/apy/:address

Calculates APY & Performance Metrics based on historical data.

Response

200 OK

{

"apy_cacao": 12.5,

"apy_usd": 15.2,

"details":{

"net_pnl_cacao": 450.5,

"current_value_cacao": 5000,

"current_value_usd": 4250,

"price_used": 0.85,

"roi_absolute_usd": 8.5

}

GET/cacao/stats

Retrieves aggregate statistics for the entire CACAO liquidity pool.

Response

200 OK

{

"global":{5 keys},

"positions":[1 items]

}

GET/maya/price

Historical Price Data

Query Parameters

Name	Type	Default	Description
interval	string	all	Timeframe for the data. Options: `24h`, `7d`, `30d`, `all`.

Response

200 OK

{

"history":[

{

"time": 1715000000000,

"priceInCacao": 42.5,

"priceInUsd": 5.2

}

"current":{

"time": 1715000000000,

"priceInCacao": 42.5,

"priceInUsd": 5.2

}

Maya Rewards

GET/maya/token-rewards/distributions

Get a summary of recent reward distributions aggregated by block height.

Query Parameters

Name	Type	Default	Description
limit	number	100	Number of distributions to return

Response

200 OK

{

"latest_block": 1234567,

"distributions":[1 items]

}

GET/maya/token-rewards/:address

Get detailed history of rewards received by a specific address.

Parameters

Name	Type	In	Description
address	string	path	Maya Protocol address
limit	number	query	Max records to return (default 100)

Response

200 OK

{

"address": "maya1...",

"total_cacao": "150000000000",

"distribution_count": 45,

"rewards":[1 items]

}

GET/maya/token-rewards/:address/total

Lightweight endpoint to get just the total accumulated rewards for an address.

Response

200 OK

{

"address": "maya1...",

"total_cacao": "150000000000",

"distribution_count": 45

}

POST/maya/token-rewards/batch

Fetch total rewards for multiple addresses in a single request. Max 50 addresses.

Request Body

json

{
  "addresses": [
    "maya1...",
    "maya1..."
  ]
}

Response

200 OK

{

"rewards":[1 items]

}

Enhanced Actions

Get enriched transaction history with historical USD values, fees, interface/affiliate info, and more. This provides a much richer view of on-chain activity than raw Midgard data.

GET/enhanced-actions/:address

Returns enriched transaction history for an address including historical USD values, detailed fees, slippage, streaming swap info, and interface attribution.

Parameters

Name	Type	In	Description
address	string	path	Maya Protocol address
limit	number	query	Max actions to return (default 50)
nextPageToken	string	query	Pagination token for next page

Response

200 OK

{

"actions":[1 items],

"meta":{2 keys}

}

Impermanent Loss

Calculate and track impermanent loss for liquidity positions. Get real-time IL analysis, historical snapshots, and summaries for your LP positions.

GET/il/:address

Get impermanent loss analysis for all liquidity positions of an address.

Response

200 OK

{

"positions":[1 items],

"totalILUSD": -1000,

"totalCurrentValueUSD": 45000

}

GET/il/:address/:pool

Get impermanent loss analysis for a specific pool position.

Parameters

Name	Type	Description
address	string	Maya Protocol address
pool	string	Pool identifier (e.g., BTC.BTC, ETH.ETH)

GET/il/:address/:pool/history

Get historical IL snapshots for a specific position over time.

Query Parameters

Name	Type	Default	Description
days	number	30	Number of days of history to return

Pool Analytics

Access detailed analytics for Maya Protocol liquidity pools including TVL, volume, LUVI (Liquidity Unit Value Index), earnings, and performance comparisons.

GET/pool-analytics

Get comprehensive analytics for all pools.

Response

200 OK

{

"pools":[1 items]

}

GET/pool-analytics/metrics

Get latest metrics snapshot for all pools.

Response

200 OK

{

"metrics":[1 items]

}

GET/pool-analytics/luvi

Get latest LUVI (Liquidity Unit Value Index) for all pools. LUVI tracks LP performance over time.

Response

200 OK

{

"pools":[1 items]

}

GET/pool-analytics/compare

Compare pool performance by LUVI over a specified period.

Query Parameters

Name	Type	Default	Description
days	number	30	Comparison period in days

GET/pool-analytics/earnings

Get aggregated earnings for all pools over a specified period.

Response

200 OK

{

"pools":[1 items],

"totalEarningsUSD": 500000

}

GET/pool-analytics/tvl-history

Get protocol-wide TVL history over time.

Response

200 OK

{

"history":[2 items]

}

GET/pool-analytics/:pool

Get detailed analytics for a specific pool.

Response

200 OK

{

"pool": "BTC.BTC",

"tvlUSD": 15000000,

"volume24hUSD": 500000,

"volume7dUSD": 3500000,

"apy": 12.5,

"luvi": 1.0523,

"assetDepth": "15000000000",

"cacaoDepth": "50000000000000",

"lpCount": 245,

"status": "available"

}

GET/pool-analytics/:pool/luvi

Get LUVI history for a specific pool.

Response

200 OK

{

"pool": "BTC.BTC",

"history":[2 items]

}

GET/pool-analytics/:pool/tvl

Get TVL history for a specific pool.

Response

200 OK

{

"pool": "BTC.BTC",

"history":[2 items]

}

GET/pool-analytics/:pool/volume

Get hourly volume data for a specific pool.

Query Parameters

Name	Type	Default	Description
hours	number	24	Number of hours of data

Rewards Attribution

Track and attribute LP rewards per address. Get detailed breakdowns by pool, daily history, forecasts, and leaderboards.

GET/rewards/:address

Get comprehensive rewards data for an address including totals and daily breakdown.

Query Parameters

Name	Type	Default	Description
days	number	30	Number of days of history

GET/rewards/:address/overview

Get rewards overview with totals for different time periods (24h, 7d, 30d, all-time).

Response

200 OK

{

"address": "maya1...",

"rewards24h":{2 keys},

"rewards7d":{2 keys},

"rewards30d":{2 keys},

"rewardsAllTime":{2 keys}

}

GET/rewards/:address/by-pool

Get rewards breakdown by pool for an address.

Response

200 OK

{

"address": "maya1...",

"pools":[2 items]

}

GET/rewards/:address/history

Get daily rewards history for charts and time-series analysis.

Response

200 OK

{

"address": "maya1...",

"history":[2 items]

}

GET/rewards/:address/forecast

Get reward forecasts for an address based on historical performance.

Query Parameters

Name	Type	Description
pool	string	Optional: filter forecasts by pool

POST/rewards/:address/sync

Trigger rewards sync/backfill for a specific address. Useful for new addresses or forcing a refresh of historical data.

Request Body

Optional

{

"days": 30,

"force": false

}

Field	Type	Default	Description
days	number	30	Number of days to sync
force	boolean	false	Force resync even if data exists

Response

200 OK

{

"success": true,

"address": "maya1...",

"attributedRecords": 30,

"skippedRecords": 0,

"alreadySynced": false,

"days": 30

}

GET/rewards/leaderboard

Get top earners leaderboard ranked by rewards earned.

Query Parameters

Name	Type	Default	Description
days	number	30	Period for ranking
limit	number	100	Max entries to return

GET/rewards/pools/aggregated

Get aggregated rewards distributed to all pools.

Response

200 OK

{

"pools":[1 items],

"totalRewardsCacao": 150000,

"totalRewardsUSD": 127500,

"days": 30

}

Protocol Stats

Access protocol-level statistics including TVL, volume, growth metrics, and the incentive pendulum status.

GET/protocol/dashboard

Get comprehensive protocol dashboard data in a single call. Includes TVL, volume, stats, and pendulum.

Response

200 OK

{

"tvl":{2 keys},

"volume":{2 keys},

"stats":{3 keys},

"pendulum":{2 keys},

"timestamp": "2024-05-01T12:00:00Z"

}

GET/protocol/stats

Get latest protocol statistics snapshot.

Response

200 OK

{

"swapCount24h": 1250,

"swapVolume24hUSD": 5000000,

"uniqueSwappers24h": 450,

"addLiquidityCount24h": 35,

"withdrawCount24h": 22,

"poolCount": 8,

"cacaoPrice": 0.85,

"timestamp": "2024-05-01T12:00:00Z"

}

GET/protocol/stats/history

Get protocol stats history over time.

Query Parameters

Name	Type	Default	Description
hours	number	168	Hours of history (default 7 days)

GET/protocol/tvl

Get current TVL breakdown by pool and asset type.

Response

200 OK

{

"totalUSD": 45000000,

"pools":[2 items],

"bonded":{1 keys},

"pooled":{1 keys}

}

GET/protocol/tvl/history

Get historical TVL data over time.

Response

200 OK

{

"history":[2 items]

}

GET/protocol/volume

Get volume aggregates (total, average daily, etc.).

Response

200 OK

{

"totalVolumeUSD": 150000000,

"avgDailyVolumeUSD": 5000000,

"volume24hUSD": 5500000,

"volume7dUSD": 35000000,

"volume30dUSD": 150000000,

"days": 30

}

GET/protocol/volume/history

Get daily volume history for charting.

Response

200 OK

{

"history":[2 items]

}

GET/protocol/pendulum

Get current incentive pendulum status. Shows the balance between node and LP incentives.

Response

200 OK

{

"bondedPercent": 67,

"pooledPercent": 33,

"targetBondPercent": 67,

"incentivePendulum": "neutral",

"nodeRewardsPercent": 67,

"lpRewardsPercent": 33,

"timestamp": "2024-05-01T12:00:00Z"

}

GET/protocol/pendulum/history

Get incentive pendulum history over time.

Response

200 OK

{

"history":[2 items]

}

GET/protocol/growth

Get protocol growth metrics with period-over-period comparisons (7d, 30d, 90d).

Response

200 OK

{

"tvl":{4 keys},

"volume":{3 keys},

"users":{2 keys}

}

Node Proxy

Beta

Access MAYANode and Midgard APIs directly through our high-availability proxy. The proxy automatically handles failover between multiple nodes and caches frequently accessed data.

GET/proxy/health

Returns a summary of the current node health status and proxy availability.

Response

200 OK

{

"status": "ok",

"nodes":{

"mayanode":{

"healthy": 3,

"total": 3

"midgard":{

"healthy": 2,

"total": 2

}

"timestamp": "2024-05-01T12:00:00Z"

}

GET/proxy/health/detailed

Returns detailed health metrics for every individual node in the proxy pool.

Response

200 OK

{

"status": "ok",

"nodes":{1 keys},

"timestamp": "2024-05-01T12:00:00Z"

}

ALL/proxy/mayanode/*

Proxies any request to a healthy MAYANode instance. Supports all standard MAYANode endpoints.

Example: Fetch Pools

text

GET https://api.cacaotracker.xyz/proxy/mayanode/mayachain/pools

Example: Fetch Last Block

text

GET https://api.cacaotracker.xyz/proxy/mayanode/mayachain/lastblock

Response includes X-Proxy-Node and X-Proxy-Time headers indicating which node handled the request.

ALL/proxy/midgard/*

Proxies any request to a healthy Midgard instance. Supports all Midgard v2 endpoints.

Example: Fetch Stats

text

GET https://api.cacaotracker.xyz/proxy/midgard/v2/stats

Example: Fetch Pools

text

GET https://api.cacaotracker.xyz/proxy/midgard/v2/pools