Developers

Authentication

Send your key on every request as Authorization: Bearer <key> and X-Api-Key: <key>. Create keys on API keys after sign-in.

Store catalog

Browse with GET /v1/catalog/*, then place store orders with POST /v1/orders.

curl -sS -H "Authorization: Bearer YOUR_KEY" \
  -H "X-Api-Key: YOUR_KEY" \
  "https://api.ethio-viral.com/v1/catalog/product/PRODUCT_ID"

Social services

List services with GET /v1/smm/services, place with POST /v1/smm/orders. This is not the same as POST /v1/orders for store checkout.

curl -sS -H "Authorization: Bearer YOUR_KEY" \
  -H "X-Api-Key: YOUR_KEY" \
  "https://api.ethio-viral.com/v1/smm/services"

Premium

Partner SKUs use /v1/premium/products, /v1/premium/orders, and delivery on /v1/premium/orders/:id/delivery.

Webhooks

Register callbacks with POST /v1/webhook. Test delivery with POST /v1/webhook/test.

MCP for AI assistants

Without a key, https://api.ethio-viral.com/mcp is read-only (catalog and prices). With ETHIOVIRAL_API_KEY, the same server can spend from that key's wallet — treat the key like cash.

{
  "mcpServers": {
    "ethio-viral": {
      "command": "npx",
      "args": ["-y", "@ethioviral/mcp"],
      "env": {
        "ETHIOVIRAL_API_KEY": "YOUR_KEY"
      }
    }
  }
}

URL clients (ChatGPT and others): connect to https://api.ethio-viral.com/mcp. Package: @ethioviral/mcp.

Errors and rate limits

JSON errors return error and message. Respect 429 responses and back off. Full schemas: OpenAPI and interactive docs.

Two things that cost money if misread:
1) Store catalog orders use POST /v1/orders (wallet in ETB). Social growth orders use POST /v1/smm/orders with a service id from GET /v1/smm/services — not POST /v1/orders.
2) Premium / partner SKUs use /v1/premium/* with their own balance and order ids. Do not mix premium order ids with store or smm cancel paths.

All v1 paths (OpenAPI)

• /v1/catalog
• /v1/catalog/categories
• /v1/catalog/category/{cat}
• /v1/catalog/search
• /v1/catalog/sections
• /v1/catalog/section/{key}
• /v1/catalog/product/{id}
• /v1/balance
• /v1/orders
• /v1/orders/{id}
• /v1/premium/products
• /v1/premium/products/{id}
• /v1/premium/balance
• /v1/premium/orders
• /v1/premium/orders/{id}
• /v1/premium/orders/{id}/delivery
• /v1/smm/services
• /v1/smm/orders
• /v1/smm/orders/{id}
• /v1/webhook
• /v1/webhook/test