# `llms.txt` for KDA API

The KDA API is an enterprise-grade Virtual Top-Up (VTU) and bill payment infrastructure. This document provides a highly condensed, LLM-friendly specification of the KDA API to help AI agents, coding assistants, and crawlers quickly understand how to interact with our services.

## Base URL
```text
https://app.kdadatasub.name.ng/api/services
```

## Authentication
All API requests must include an `Authorization` header with a valid Bearer token.
```http
Authorization: Bearer <API_KEY>
Content-Type: application/json
```
**Environments:** The environment is determined entirely by the API key prefix. There is no separate sandbox URL.
- **Sandbox:** Keys starting with `kds_test_`. Simulates a successful response without deducting real funds.
- **Production:** Keys starting with `kds_live_`.

**Key Scopes:**
- **Service Keys:** Used for purchasing services (Data, Airtime, TV, etc.).
- **Profile Keys:** Used for account-level actions (Balance, Transaction History).

## Standard Response Format
All endpoints return a standard JSON structure:
```json
{
  "success": true, // or false
  "message": "Human readable message",
  "data": { ... } // Payload on success
}
```
Failed transactions return standard HTTP status codes (`400`, `401`, `403`, `404`, `500`) with an error payload:
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Detailed error message"
  }
}
```

## Core Endpoints

### 1. Account Balance
- **Endpoint**: `GET /balance`
- **Scope**: Profile Key
- **Response**: `{ "success": true, "data": { "balance": 5000.00, "currency": "NGN" } }`

### 2. Fetch Providers & Plans
Every service has a `/plans` endpoint to fetch available providers and pricing.
- **Data**: `GET /data/plans`
- **Airtime**: `GET /airtime/plans`
- **TV**: `GET /tv/plans`
- **Electricity**: `GET /electricity/plans`
- **Exams**: `GET /exam/plans`
- **Data Cards**: `GET /data-card/plans`
- **Recharge Cards**: `GET /recharge-card/plans`

### 3. Purchase Services
All purchases are made via `POST` requests. An `idempotencyKey` (UUID) is heavily recommended to prevent duplicate charges.

**Data Purchase:** `POST /data`
```json
{ "planId": "string", "number": "string", "isPorted": boolean, "idempotencyKey": "uuid" }
```

**Airtime Purchase:** `POST /airtime`
```json
{ "planId": "string", "number": "string", "amount": number, "idempotencyKey": "uuid" }
```

**TV Subscription:** `POST /tv`
```json
{ "planId": "string", "iucNumber": "string", "idempotencyKey": "uuid" }
```

**Electricity Bill:** `POST /electricity`
```json
{ "providerId": "string", "meterNumber": "string", "amount": number, "meterType": "PREPAID|POSTPAID", "idempotencyKey": "uuid" }
```

**Exam PINs:** `POST /exam`
```json
{ "providerId": "string", "quantity": number, "cardName": "string", "idempotencyKey": "uuid" }
```

**Data Card Purchase:** `POST /data-card`
```json
{ "planId": "string", "quantity": number, "cardName": "string", "idempotencyKey": "uuid" }
```

**Recharge Card Purchase:** `POST /recharge-card`
```json
{ "planId": "string", "quantity": number, "cardName": "string", "idempotencyKey": "uuid" }
```

### 4. Transactions History
- **Endpoint**: `GET /transactions`
- **Query Params**: `?page=1&limit=20&type=DATA`
- **Scope**: Profile Key

## Idempotency
Provide a unique UUID in the `idempotencyKey` field for `POST` requests. If a request is retried with the same key within 24 hours, the API will return the original response without double-charging the wallet.