API Documentation

Access real-time Ethiopian Birr exchange rates and P2P market data for your applications

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.

API Access

To get API access and integration support, please contact us or join our Telegram group.

Base URL

All API requests should be made to:

https://ethioblackmarket.com

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
GET

/api/latest-prices

Returns the latest exchange rates for all supported currencies with optional time period aggregation.

Query Parameters

ParameterTypeRequiredDescription
period string No Aggregation period: all, hourly, daily, weekly, monthly. Default: all

Code Examples

cURL
curl -X GET "https://ethioblackmarket.com/api/latest-prices?period=daily"
JavaScript
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));
Python
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 } }
  ]
}
GET

/api/historical-prices

Returns historical price data before a specified timestamp. Useful for pagination and loading older data.

Query Parameters

ParameterTypeRequiredDescription
before integer Yes Unix timestamp. Returns prices before this time.
period string No Aggregation period: all, hourly, daily, weekly, monthly

Code Examples

cURL
curl -X GET "https://ethioblackmarket.com/api/historical-prices?before=1703088000&period=hourly"
JavaScript
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);
  });
Python
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 } }
  ]
}
GET

/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
curl -X GET "https://ethioblackmarket.com/api/price-history-range"
JavaScript
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);
  });
Python
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 } }
  ]
}
GET

/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
curl -X GET "https://ethioblackmarket.com/totalSupplyAndDemand"
JavaScript
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);
  });
Python
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
}
GET

/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
curl -X GET "https://ethioblackmarket.com/supplyAndDemandByPrice"
JavaScript
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);
  });
Python
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
  }
}
GET

/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
curl -X GET "https://ethioblackmarket.com/lastMarketActions"
JavaScript
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`);
    });
  });
Python
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
  }
]
GET

/api/currencies

Returns a list of all supported currencies, separated into popular and other categories.

Query Parameters

No parameters required.

Code Examples

cURL
curl -X GET "https://ethioblackmarket.com/api/currencies"
JavaScript
fetch('https://ethioblackmarket.com/api/currencies')
  .then(response => response.json())
  .then(data => {
    console.log('Popular currencies:', data.popular);
    console.log('Other currencies:', data.others);
  });
Python
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" }
  ]
}
GET

/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
curl -X GET "https://ethioblackmarket.com/api/commercialbankrates"
JavaScript
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);
  });
Python
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
  }
]
GET

/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
curl -X GET "https://ethioblackmarket.com/api/latest-bank-rates"
JavaScript
fetch('https://ethioblackmarket.com/api/latest-bank-rates')
  .then(response => response.json())
  .then(data => {
    data.forEach(currency => {
      console.log(`${currency.currency_code}:`, currency.rates);
    });
  });
Python
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 }
    ]
  }
]
GET

/api/blogs

Returns a list of blog posts with titles, dates, summaries, and full content.

Query Parameters

No parameters required.

Code Examples

cURL
curl -X GET "https://ethioblackmarket.com/api/blogs"
JavaScript
fetch('https://ethioblackmarket.com/api/blogs')
  .then(response => response.json())
  .then(blogs => {
    blogs.forEach(blog => {
      console.log(`${blog.title} - ${blog.date}`);
    });
  });
Python
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..."
  }
]
GET

/api/faqs

Returns frequently asked questions and their answers.

Query Parameters

No parameters required.

Code Examples

cURL
curl -X GET "https://ethioblackmarket.com/api/faqs"
JavaScript
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);
    });
  });
Python
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 CodeDescription
200Success - Request completed successfully
403Forbidden - IP has been banned due to rate limit violations
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end
503Service Unavailable - Data not yet available (e.g., P2P data still loading)

Error Response Format

{
  "error": "Error message describing what went wrong"
}