Introduction
The EthioBlackMarket API provides access to real-time and historical exchange rate data for Ethiopian Birr (ETB) against multiple currencies. Data is sourced from Binance P2P markets and Ethiopian commercial banks.
To get API access and integration support, please contact us or join our Telegram group.
Base URL
All API requests should be made to:
Rate Limiting
The API is rate-limited to ensure fair usage and stability:
- 5,000 requests per 15 minutes per IP address
- Exceeding the limit results in temporary blocking
- Repeated violations may result in permanent IP ban
/api/latest-prices
Returns the latest exchange rates for all supported currencies with optional time period aggregation.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
period |
string | No | Aggregation period: all, hourly, daily, weekly, monthly. Default: all |
Code Examples
curl -X GET "https://ethioblackmarket.com/api/latest-prices?period=daily"
fetch('https://ethioblackmarket.com/api/latest-prices?period=daily')
.then(response => response.json())
.then(data => {
console.log('Current USD rate:', data.usdCurrentBlackPrice);
console.log('Daily change:', data.dailyPercentage + '%');
})
.catch(error => console.error('Error:', error));
import requests
response = requests.get(
'https://ethioblackmarket.com/api/latest-prices',
params={'period': 'daily'}
)
data = response.json()
print(f"Current USD rate: {data['usdCurrentBlackPrice']}")
print(f"Daily change: {data['dailyPercentage']}%")
Response
{
"usdCurrentBlackPrice": 127.50,
"dailyPercentage": 0.35,
"openingPrice": 127.05,
"closingPrice": 127.40,
"range": { "max": "128.00", "min": "126.50" },
"allLastprice": {
"USD": 127.50,
"EUR": 134.20,
"GBP": 156.80,
"SAR": 33.98
},
"historicalPrices": [
{ "time": 1703088000, "value": { "USD": 127.30, "EUR": 134.10 } }
]
}
/api/historical-prices
Returns historical price data before a specified timestamp. Useful for pagination and loading older data.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
before |
integer | Yes | Unix timestamp. Returns prices before this time. |
period |
string | No | Aggregation period: all, hourly, daily, weekly, monthly |
Code Examples
curl -X GET "https://ethioblackmarket.com/api/historical-prices?before=1703088000&period=hourly"
const timestamp = Math.floor(Date.now() / 1000) - 86400; // 24 hours ago
fetch(`https://ethioblackmarket.com/api/historical-prices?before=${timestamp}&period=hourly`)
.then(response => response.json())
.then(data => {
console.log('Historical prices:', data.historicalPrices);
});
import requests
import time
timestamp = int(time.time()) - 86400 # 24 hours ago
response = requests.get(
'https://ethioblackmarket.com/api/historical-prices',
params={'before': timestamp, 'period': 'hourly'}
)
data = response.json()
print(f"Found {len(data['historicalPrices'])} historical records")
Response
{
"historicalPrices": [
{ "time": 1703001600, "value": { "USD": 126.80, "EUR": 133.50 } },
{ "time": 1702998000, "value": { "USD": 126.75, "EUR": 133.45 } }
]
}
/api/price-history-range
Returns the available date range of price data along with monthly aggregated prices. Useful for inflation/purchasing power calculations.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/api/price-history-range"
fetch('https://ethioblackmarket.com/api/price-history-range')
.then(response => response.json())
.then(data => {
console.log('Data available from:', new Date(data.earliest * 1000));
console.log('Data available to:', new Date(data.latest * 1000));
console.log('Monthly prices:', data.monthlyPrices);
});
import requests
from datetime import datetime
response = requests.get('https://ethioblackmarket.com/api/price-history-range')
data = response.json()
earliest = datetime.fromtimestamp(data['earliest'])
latest = datetime.fromtimestamp(data['latest'])
print(f"Data range: {earliest} to {latest}")
Response
{
"earliest": 1672531200,
"latest": 1703088000,
"monthlyPrices": [
{ "month": "2024-01", "value": { "USD": 125.50, "EUR": 132.80 } },
{ "month": "2024-02", "value": { "USD": 126.20, "EUR": 133.50 } }
]
}
/totalSupplyAndDemand
Returns the total USDT supply (sellers) and demand (buyers) from the Binance P2P market for ETB.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/totalSupplyAndDemand"
fetch('https://ethioblackmarket.com/totalSupplyAndDemand')
.then(response => response.json())
.then(data => {
console.log('Total Supply (USDT):', data.totalSupply);
console.log('Total Demand (USDT):', data.totalDemand);
});
import requests
response = requests.get('https://ethioblackmarket.com/totalSupplyAndDemand')
data = response.json()
print(f"Total Supply: {data['totalSupply']:,.2f} USDT")
print(f"Total Demand: {data['totalDemand']:,.2f} USDT")
Response
{
"totalSupply": 125430.50,
"totalDemand": 98750.25
}
/supplyAndDemandByPrice
Returns supply and demand grouped by the top 5 price levels. Shows market depth at different price points.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/supplyAndDemandByPrice"
fetch('https://ethioblackmarket.com/supplyAndDemandByPrice')
.then(response => response.json())
.then(data => {
console.log('Supply by price:', data.supplyGrouped);
console.log('Demand by price:', data.demandGrouped);
});
import requests
response = requests.get('https://ethioblackmarket.com/supplyAndDemandByPrice')
data = response.json()
for price, amount in data['supplyGrouped'].items():
print(f"Supply at {price} ETB: {amount} USDT")
Response
{
"supplyGrouped": {
"127.50": 15420.50,
"127.60": 12350.00,
"127.70": 8920.25,
"127.80": 5430.00,
"128.00": 3200.75
},
"demandGrouped": {
"127.40": 18750.00,
"127.30": 14200.50,
"127.20": 9850.25,
"127.10": 6420.00,
"127.00": 4100.50
}
}
/lastMarketActions
Returns the last 100 market actions (buy/sell events) from the P2P market, filtered to realistic price ranges.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/lastMarketActions"
fetch('https://ethioblackmarket.com/lastMarketActions')
.then(response => response.json())
.then(actions => {
actions.forEach(action => {
console.log(`${action.action}: ${action.amount} USDT at ${action.price} ETB`);
});
});
import requests
response = requests.get('https://ethioblackmarket.com/lastMarketActions')
actions = response.json()
for action in actions[:10]: # Show first 10
print(f"{action['action']}: {action['amount']} USDT at {action['price']} ETB")
Response
[
{
"timestamp": "2024-12-20T10:30:00.000Z",
"activityType": "BUYER",
"advertiser": "trader123",
"advNo": "123456789",
"action": "bought",
"amount": 500.00,
"price": 127.50
},
{
"timestamp": "2024-12-20T10:28:30.000Z",
"activityType": "SELLER",
"advertiser": "seller456",
"advNo": "987654321",
"action": "sold",
"amount": 250.00,
"price": 127.45
}
]
/api/currencies
Returns a list of all supported currencies, separated into popular and other categories.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/api/currencies"
fetch('https://ethioblackmarket.com/api/currencies')
.then(response => response.json())
.then(data => {
console.log('Popular currencies:', data.popular);
console.log('Other currencies:', data.others);
});
import requests
response = requests.get('https://ethioblackmarket.com/api/currencies')
data = response.json()
for currency in data['popular']:
print(f"{currency['code']}: {currency['name']}")
Response
{
"popular": [
{ "code": "USD", "name": "", "link": "/" },
{ "code": "EUR", "name": "euro", "link": "/euro" },
{ "code": "GBP", "name": "pound", "link": "/pound" },
{ "code": "SAR", "name": "saudiriyal", "link": "/saudiriyal" }
],
"others": [
{ "code": "AED", "name": "dirham", "link": "/dirham" },
{ "code": "CAD", "name": "canadiandollar", "link": "/canadiandollar" }
]
}
/api/commercialbankrates
Returns current exchange rates from the Commercial Bank of Ethiopia (CBE), including cash and transactional rates.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/api/commercialbankrates"
fetch('https://ethioblackmarket.com/api/commercialbankrates')
.then(response => response.json())
.then(rates => {
const usd = rates.find(r => r.currencyCode === 'USD');
console.log('USD Buying:', usd.cashBuying);
console.log('USD Selling:', usd.cashSelling);
});
import requests
response = requests.get('https://ethioblackmarket.com/api/commercialbankrates')
rates = response.json()
for rate in rates:
print(f"{rate['currencyCode']}: Buy {rate['cashBuying']}, Sell {rate['cashSelling']}")
Response
[
{
"currencyCode": "USD",
"currencyName": "US Dollar",
"cashBuying": 56.50,
"cashSelling": 57.65,
"transactionalBuying": 56.50,
"transactionalSelling": 57.65
},
{
"currencyCode": "EUR",
"currencyName": "Euro",
"cashBuying": 61.20,
"cashSelling": 62.45,
"transactionalBuying": 61.20,
"transactionalSelling": 62.45
}
]
/api/latest-bank-rates
Returns the latest exchange rates from multiple Ethiopian banks via Enjaz. Data is cached for 5 minutes.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/api/latest-bank-rates"
fetch('https://ethioblackmarket.com/api/latest-bank-rates')
.then(response => response.json())
.then(data => {
data.forEach(currency => {
console.log(`${currency.currency_code}:`, currency.rates);
});
});
import requests
response = requests.get('https://ethioblackmarket.com/api/latest-bank-rates')
data = response.json()
for currency in data:
print(f"{currency['currency_code']}: {currency['rates']}")
Response
[
{
"currency_code": "USD",
"rates": [
{ "bank": "CBE", "buying": 56.50, "selling": 57.65 },
{ "bank": "Awash", "buying": 56.45, "selling": 57.70 }
]
}
]
/api/blogs
Returns a list of blog posts with titles, dates, summaries, and full content.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/api/blogs"
fetch('https://ethioblackmarket.com/api/blogs')
.then(response => response.json())
.then(blogs => {
blogs.forEach(blog => {
console.log(`${blog.title} - ${blog.date}`);
});
});
import requests
response = requests.get('https://ethioblackmarket.com/api/blogs')
blogs = response.json()
for blog in blogs:
print(f"{blog['title']} ({blog['date']})")
Response
[
{
"title": "Understanding ETB Exchange Rates",
"date": "December 15, 2024",
"content": "Summary of the blog post...",
"imageUrl": "https://ethioblackmarket.com/images/blog1.jpg",
"path": "/blog1",
"fullBlog": "Full HTML content of the blog..."
}
]
/api/faqs
Returns frequently asked questions and their answers.
Query Parameters
No parameters required.
Code Examples
curl -X GET "https://ethioblackmarket.com/api/faqs"
fetch('https://ethioblackmarket.com/api/faqs')
.then(response => response.json())
.then(faqs => {
faqs.forEach(faq => {
console.log('Q:', faq.question);
console.log('A:', faq.answer);
});
});
import requests
response = requests.get('https://ethioblackmarket.com/api/faqs')
faqs = response.json()
for faq in faqs:
print(f"Q: {faq['question']}")
print(f"A: {faq['answer']}\n")
Response
[
{
"question": "What is the black market exchange rate?",
"answer": "The black market rate is the unofficial exchange rate..."
},
{
"question": "How often is the data updated?",
"answer": "Prices are updated in real-time from Binance P2P..."
}
]
Error Handling
The API returns standard HTTP status codes to indicate success or failure:
| Status Code | Description |
|---|---|
200 | Success - Request completed successfully |
403 | Forbidden - IP has been banned due to rate limit violations |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error - Something went wrong on our end |
503 | Service Unavailable - Data not yet available (e.g., P2P data still loading) |
Error Response Format
{
"error": "Error message describing what went wrong"
}