API Documentation
The Oracle API provides real-time access to token pricing data, historical price information, and statistical analysis. This API is designed for developers building applications that need reliable, up-to-date token metrics.
Base URL:
https://oracle.returnity.io/apiQuick Start
Get started with a simple request to fetch current oracle data:
fetch('https://oracle.returnity.io/api/oracle')
.then(res => res.json())
.then(data => console.log(data));Authentication
The Oracle API is publicly accessible and does not require authentication. However, requests are subject to rate limiting based on your IP address.
Get Oracle Data
Retrieve current token pricing and performance metrics.
GET /oracle
Response
{
"tokenPrice": "0.010000000000000000",
"equity": "4000",
"performance": "0.00",
"returnPct": "0.00",
"poolValue": "4000.00",
"feeAmount": "0.00",
"lastUpdate": "2025-10-05T00:00:00.000Z"
}Response Fields
tokenPriceCurrent token price with 18 decimal precisionequityCurrent equity value in USDperformanceAbsolute performance in USDreturnPctReturn percentage since inceptionpoolValueAdjusted pool value after feesfeeAmountPerformance fee collectedlastUpdateISO 8601 timestamp of last updateGet Price History
Retrieve historical price data for charting and analysis.
GET /oracle/history
Query Parameters
hoursNumber of hours to look back (1-168). Default: 24Response
{
"data": [
{
"id": 1,
"timestamp": 1728000000000,
"token_price": "0.010000000000000000",
"equity": "4000.00",
"performance": "0.00",
"return_pct": "0.00",
"pool_value": "4000.00",
"fee_amount": "0.00",
"created_at": "2025-10-05T00:00:00.000Z"
}
],
"meta": {
"count": 96,
"hours": 24,
"totalRecords": 1000
}
}Get Statistics
Retrieve aggregated statistical data for a time period.
GET /oracle/stats
Query Parameters
hoursNumber of hours to analyze (1-168). Default: 24Response
{
"statistics": {
"totalRecords": 96,
"timeRange": {
"hours": 24,
"firstRecord": "2025-10-04T00:00:00.000Z",
"lastRecord": "2025-10-05T00:00:00.000Z"
},
"tokenPrice": {
"min": 0.01,
"max": 0.01,
"avg": 0.01,
"current": 0.01,
"volatility": 0.0,
"change": 0.0
},
"equity": {
"min": 4000.00,
"max": 4000.00,
"avg": 4000.00,
"change": 0.00
},
"performance": {
"min": 0.00,
"max": 0.00,
"avg": 0.00
}
},
"allTimeRecords": 1000,
"generatedAt": "2025-10-05T00:00:00.000Z"
}Rate Limits
To ensure fair usage and system stability, the API enforces rate limits based on IP address.
Requests per hour
100
Time window
60 min
When you exceed the rate limit, you will receive a 429 Too Many Requests response. The limit resets on a rolling hourly window.
Rate Limit Headers
All API responses include headers to help you monitor your rate limit status.
X-RateLimit-LimitTotal requests allowed per hourX-RateLimit-RemainingRequests remaining in current windowX-RateLimit-ResetSeconds until the limit resetsRetry-AfterSeconds to wait before retrying (on 429 errors)Example: JavaScript
async function getOracleData() {
try {
const response = await fetch(
'https://oracle.returnity.io/api/oracle'
);
// Check rate limit headers
const remaining = response.headers.get(
'X-RateLimit-Remaining'
);
console.log('Requests remaining:', remaining);
if (!response.ok) {
if (response.status === 429) {
const retryAfter = response.headers.get(
'Retry-After'
);
console.error(
'Rate limited. Retry after',
retryAfter,
'seconds'
);
return;
}
throw new Error('API error');
}
const data = await response.json();
console.log('Token Price:', data.tokenPrice);
console.log('Performance:', data.returnPct + '%');
return data;
} catch (error) {
console.error('Failed to fetch:', error);
}
}
// Fetch history
async function getPriceHistory(hours = 24) {
const response = await fetch(
`https://oracle.returnity.io/api/oracle/history?hours=${hours}`
);
const { data, meta } = await response.json();
console.log(`Retrieved ${meta.count} records`);
return data;
}
// Fetch statistics
async function getStatistics(hours = 24) {
const response = await fetch(
`https://oracle.returnity.io/api/oracle/stats?hours=${hours}`
);
const { statistics } = await response.json();
console.log('Average price:', statistics.tokenPrice.avg);
return statistics;
}Example: Python
import requests
import time
BASE_URL = "https://oracle.returnity.io/api"
def get_oracle_data():
"""Fetch current oracle data"""
try:
response = requests.get(
f"{BASE_URL}/oracle"
)
# Check rate limit headers
remaining = response.headers.get(
'X-RateLimit-Remaining'
)
print(f"Requests remaining: {remaining}")
if response.status_code == 429:
retry_after = int(
response.headers.get('Retry-After', 60)
)
print(f"Rate limited. Waiting {retry_after}s...")
time.sleep(retry_after)
return get_oracle_data() # Retry
response.raise_for_status()
data = response.json()
print(f"Token Price: {data['tokenPrice']}")
print(f"Performance: {data['returnPct']}%")
return data
except requests.exceptions.RequestException as e:
print(f"Error fetching data: {e}")
return None
def get_price_history(hours=24):
"""Fetch historical price data"""
response = requests.get(
f"{BASE_URL}/oracle/history",
params={"hours": hours}
)
response.raise_for_status()
result = response.json()
print(f"Retrieved {result['meta']['count']} records")
return result['data']
def get_statistics(hours=24):
"""Fetch statistical analysis"""
response = requests.get(
f"{BASE_URL}/oracle/stats",
params={"hours": hours}
)
response.raise_for_status()
result = response.json()
stats = result['statistics']
print(f"Average price: {stats['tokenPrice']['avg']}")
return stats
if __name__ == "__main__":
oracle_data = get_oracle_data()
history = get_price_history(hours=24)
stats = get_statistics(hours=24)Example: cURL
# Get current oracle data curl -i https://oracle.returnity.io/api/oracle # Get 24-hour price history curl https://oracle.returnity.io/api/oracle/history?hours=24 # Get 7-day statistics curl https://oracle.returnity.io/api/oracle/stats?hours=168 # Check rate limit status (verbose) curl -v https://oracle.returnity.io/api/oracle 2>&1 | \ grep -i ratelimit