PunkPredictor API Documentation
PunkPredictor: The most accurate valuation tool for CryptoPunks. Find deals and make informed decisions.
Welcome to the PunkPredictor API documentation. PunkPredictor is the most accurate AI-powered valuation model for CryptoPunks, providing real-time price predictions, historical valuations, and market analytics for NFT collectors and investors.
Our advanced machine learning algorithms analyze multiple factors including rarity, attributes, historical sales data, and market trends to deliver precise valuations that give you an edge in the CryptoPunk market.
https://api.punkpredictor.xyzhttps://api.punkpredictor.xyz/ENDPOINT_NAME. You can query by punk ID (0-9999) for most endpoints
that require specific punk data.
Key Features
As the most accurate valuation tool for CryptoPunks, PunkPredictor helps you find deals and make informed decisions with these features:
- Accurate Price Predictions: Get current estimated values for any CryptoPunk with our model
- Historical Valuations: Access historical price data to track value changes over time
- Market Analytics: Monitor floor price changes and average valuation trends
- Attribute-Based Analysis: Understand how specific attributes impact punk valuations
Authentication
All API requests require an API key that should be included in the request body. PunkPredictor offers exclusive membership access with limited availability to ensure premium service quality.
To get your API key:
- Purchase a subscription to PunkPredictor
- Once your payment is confirmed, the site will be unlocked
- Click on the key icon located in the bottom right corner of the screen
- Your unique API key will be displayed and can be copied for use in your applications
Your API key is automatically generated when you subscribe to our service and can be accessed at any time through the key icon after logging in.
Rate Limits
The API is rate limited to 30 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.
Our rate limits are designed to ensure fair usage and optimal performance for all members. For applications requiring higher limits, please contact our support team.
Response Status Codes
| Status Code | Description |
|---|---|
200 OK |
Request successful |
400 Bad Request |
Invalid parameters or missing required fields |
401 Unauthorized |
Invalid or missing API key |
429 Too Many Requests |
Rate limit exceeded |
500 Server Error |
Internal server error |
API Endpoints
Predict the Price of a Punk Today
Get the current predicted price for a specific CryptoPunk.
Parameters
| Parameter | Type | Description |
|---|---|---|
| id_punk Required | integer | The ID of the CryptoPunk (0-9999) |
| api_key Required | string | Your API key for authentication |
Python Example
import requests
# Base URL
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def predict_price_of_punk(id_punk, api_key):
url = f"{BASE_URL}/predict_price_of_a_punk_today"
data = {
"id_punk": id_punk,
"api_key": api_key
}
response = requests.post(url, json=data)
return response.json()
# Example Usage
result = predict_price_of_punk(1234, api_key)
print(result)
Try it
Response
200 OKGet Punk Historical Valuations
Retrieve historical price valuations for a specific CryptoPunk.
Parameters
| Parameter | Type | Description |
|---|---|---|
| punk_id Required | integer | The ID of the CryptoPunk (0-9999) |
| api_key Required | string | Your API key for authentication |
Python Example
import requests
# Base URL
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def get_punk_history(punk_id, api_key):
url = f"{BASE_URL}/get_punk_history"
data = {
"punk_id": punk_id,
"api_key": api_key
}
response = requests.post(url, json=data)
return response.json()
# Example Usage
result = get_punk_history(1234, api_key)
print(result)
Try it
Response
200 OKGet Punk Sales History
Retrieve sales history for a specific CryptoPunk including floor price context and metadata.
Parameters
| Parameter | Type | Description |
|---|---|---|
| punk_id Required | integer | The ID of the CryptoPunk (0-9999) |
| api_key Required | string | Your API key for authentication |
Python Example
import requests
# Base URL
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def get_punk_sales(punk_id, api_key):
url = f"{BASE_URL}/get_punksales"
data = {
"punk_id": punk_id,
"api_key": api_key
}
response = requests.post(url, json=data)
return response.json()
# Example Usage
result = get_punk_sales(1234, api_key)
print(result)
Try it
Response
200 OKGet Punk Traits
Retrieve traits for one or more CryptoPunks by their IDs.
Parameters
| Parameter | Type | Description |
|---|---|---|
| punk_ids Required | array | Array of CryptoPunk IDs (0-9999) |
| api_key Required | string | Your API key for authentication |
Python Example
import requests
# Base URL
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def get_punk_traits(punk_ids, api_key):
url = f"{BASE_URL}/get_punk_traits"
data = {
"punk_ids": punk_ids,
"api_key": api_key
}
response = requests.post(url, json=data)
return response.json()
# Example Usage
result = get_punk_traits([1234, 5678, 9999], api_key)
print(result)
Try it
Response
200 OKGet Sales by Specific Traits
Retrieve sales data for CryptoPunks that have ALL specified traits (AND operation).
Parameters
| Parameter | Type | Description |
|---|---|---|
| traits Required | array | Array of trait names to filter by |
| page | integer | Page number for pagination (default: 1) |
| limit | integer | Number of results per page (default: 5, max: 1000) |
| api_key Required | string | Your API key for authentication |
Python Example
import requests
# Base URL
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def get_sales_by_traits(traits, api_key, page=1, limit=5):
url = f"{BASE_URL}/get_sales_by_specific_traits"
data = {
"traits": traits,
"page": page,
"limit": limit,
"api_key": api_key
}
response = requests.post(url, json=data)
return response.json()
# Example Usage
result = get_sales_by_traits(["3D Glasses", "Beanie"], api_key)
print(result)
Try it
Response
200 OKActive Listings
Retrieve all current active listings from the marketplace, sorted by price. Useful for finding the lowest priced Punks.
Parameters
No parameters required.
Response Format
Returns a JSON array of active listings.
[
{
"Punk ID": "8888",
"ETH Price": 24.5,
"USD Price": 45120.50,
"source": "Punks Marketplace"
},
...
]
Try it out
Response
200 OKLending Data
Retrieve lending data for CryptoPunk-backed loans across all major platforms (Gondi, NFTfi, Blur/Blend, Arcade). Supports filtering by punk ID, lender, borrower, status, and platform.
Parameters
| Parameter | Type | Description |
|---|---|---|
| X-API-Key Required | string | Your API key for authentication (sent in header) |
| punk_id | integer | Optional. Filter loans for a specific CryptoPunk ID (0-9999) |
| lender | string | Optional. Filter by lender address or ENS name (partial match supported) |
| borrower | string | Optional. Filter by borrower address or ENS name (partial match supported) |
| status | string | Optional. Filter by loan status: "active", "repaid", or "defaulted" |
| platform | string | Optional. Filter by platform: "gondi", "nftfi", "blur" (or "blend"), "arcade" |
| page | integer | Optional. Page number for pagination (default: 1) |
| limit | integer | Optional. Results per page (default: 100, max: 500) |
Response Format
Returns paginated loan data with aggregate statistics for filtered results:
{
"data": [
{
"token_id": 1234,
"platform": "gondi",
"lender": "0x1234...",
"lender_ens": "lender.eth",
"borrower": "0x5678...",
"borrower_ens": "borrower.eth",
"principal": 5.0,
"principal_symbol": "WETH",
"apr": 12.5,
"effective_apr": 15.2,
"duration_days": 30,
"LTV": 0.65,
"status": "active",
"type": "initiated",
"date": "2024-01-15",
"end_date": "2024-02-14"
}
],
"pagination": {
"total": 10258,
"page": 1,
"limit": 100,
"pages": 103
},
"filteredStats": {
"totalLoans": 4445,
"avgLTV": 58.47,
"avgDuration": 56.03,
"avgAPR": 15.24,
"defaultRate": 2.43,
"activeLoans": 198
}
}
Python Example
import requests
# Base URL
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def get_lending_data(api_key, punk_id=None, lender=None, borrower=None,
status=None, platform=None):
url = f"{BASE_URL}/get_lending_data"
params = {}
if punk_id is not None:
params['punk_id'] = punk_id
if lender:
params['lender'] = lender
if borrower:
params['borrower'] = borrower
if status:
params['status'] = status
if platform:
params['platform'] = platform
headers = {
'X-API-Key': api_key,
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers, params=params)
return response.json()
# Example: Get all Gondi loans
result = get_lending_data(api_key, platform='gondi')
print(f"Found {result['filteredStats']['totalLoans']} Gondi loans")
# Example: Get loans by lender ENS
result = get_lending_data(api_key, lender='tatsu.eth')
print(result)
# Example: Get active loans for a specific punk
result = get_lending_data(api_key, punk_id=1234, status='active')
print(result)
Try it
Response
200 OKLending Pre-computed Analytics
Retrieve pre-computed analytics for CryptoPunk lending including monthly charts, risk curves, yield curves, DTD shock analysis, and top lenders/borrowers. Supports the same filters as /get_lending_data for filtered analytics.
Parameters
| Parameter | Type | Description |
|---|---|---|
| X-API-Key Required | string | Your API key for authentication (sent in header) |
| punk_id | integer | Optional. Filter analytics for a specific CryptoPunk ID |
| lender | string | Optional. Filter by lender address or ENS name |
| borrower | string | Optional. Filter by borrower address or ENS name |
| status | string | Optional. Filter by loan status |
| platform | string | Optional. Filter by platform |
Response Format
Returns pre-computed analytics data optimized for chart rendering:
{
"success": true,
"analytics": {
"summary": {
"totalLoans": 10258,
"avgLTV": 58.72,
"avgDuration": 56.03,
"avgAPR": 15.78,
"defaultRate": 2.65
},
"monthlyCharts": {
"ltv": [{"month": "2024-01", "average": 0.58, "count": 150}],
"duration": [{"month": "2024-01", "average": 45.2, "count": 150}],
"apr": [{"month": "2024-01", "average": 15.5, "count": 150}],
"platform": [{"month": "2024-01", "gondi": 80, "nftfi": 50, "blur": 20}],
"defaultRate": [{"month": "2024-01", "total": 150, "defaults": 3, "defaultRate": 2.0}],
"uniqueLenders": [{"month": "2024-01", "uniqueLenders": 45}]
},
"riskCurves": {
"gondi": {
"40-60%": {"30-60d": {"defaultRate": 1.2, "loanCount": 156}}
}
},
"yieldCurve": {
"total": [{"duration": "0-7d", "avgAPR": 18.5, "count": 50}],
"byPlatform": {...}
},
"dtdShock": [
{"label": "-20%", "drop": -20, "principalAtRisk": 150.5, "loanCount": 45}
],
"topLenders": [...],
"topBorrowers": [...]
}
}
Python Example
import requests
BASE_URL = 'https://api.punkpredictor.xyz'
api_key = 'YOUR_API_KEY'
def get_lending_analytics(api_key, platform=None, status=None):
url = f"{BASE_URL}/lending/analytics"
params = {}
if platform:
params['platform'] = platform
if status:
params['status'] = status
headers = {'X-API-Key': api_key}
response = requests.get(url, headers=headers, params=params)
return response.json()
# Get overall analytics
result = get_lending_analytics(api_key)
summary = result['analytics']['summary']
print(f"Total loans: {summary['totalLoans']}")
print(f"Avg LTV: {summary['avgLTV']}%")
print(f"Default rate: {summary['defaultRate']}%")
# Get Gondi-specific analytics
gondi_result = get_lending_analytics(api_key, platform='gondi')
print(f"Gondi loans: {gondi_result['analytics']['summary']['totalLoans']}")