# Ethio-Viral API

> REST API for reselling digital goods in Ethiopia: browse 10,000+ gift cards, airtime, eSIM and subscriptions, check your wallet, place orders and collect the delivery code.

## Documentation

- Developer guide: https://api.ethio-viral.com/docs/v1
- OpenAPI spec (JSON): https://api.ethio-viral.com/docs/v1/openapi.json

The documentation page also embeds the full OpenAPI spec in HTML at `#ethio-viral-api-openapi-spec`.

## API base URL

https://api.ethio-viral.com/v1

## Authentication

- Header `Authorization: Bearer evk_YOUR_KEY`, or `X-API-Key: evk_YOUR_KEY`
- Create and revoke keys at https://ethio-viral.com/api-keys or https://store.ethio-viral.com/profile/api-keys — both issue the same key
- One key opens all three products: Store (`/v1/catalog`, `/v1/orders`), Premium (`/v1/premium/*`) and SMM (`/v1/smm/*`), spending one wallet
- Keys begin `evk_` or `evk_live_` depending on where they were made; both are accepted everywhere
- An MCP server is published as `@ethioviral/mcp` — an AI assistant can use these endpoints directly via `npx -y @ethioviral/mcp` with ETHIOVIRAL_API_KEY set

## Two things that cost money if misread

- Prices are `denoms[].retailMinor` in **ETB santim**: 199000 means ETB 1,990.00. Send that integer as `denomination`.
- `POST /v1/orders` requires an `Idempotency-Key` header. Without it, a retry after a timeout buys twice.

## Typical flow

GET /v1/catalog (paged, or ?since= for changes) -> GET /v1/catalog/product/{id} -> POST /v1/orders -> GET /v1/orders/{id} until fulfilled -> read deliveryPayload