<?php
// Kuvola Institutional Data API — PHP starter (no Composer package published; copy this file)

class KuvolaClient
{
    private const BASE_URL = "https://kuvola.ao";

    public function __construct(private string $apiKey) {}

    public function v2ListMarkets(array $params = []): array
    {
        $url = self::BASE_URL . "/api/v2/markets" . (count($params) ? "?" . http_build_query($params) : "");

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer {$this->apiKey}"]);

        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $decoded = json_decode($body, true);

        if ($status === 429) {
            throw new Exception("Rate limited.");
        }
        if ($status >= 400) {
            throw new Exception("Kuvola API error {$status}: " . ($decoded['error']['message'] ?? 'Unknown error'));
        }
        return $decoded; // ['data' => ..., 'pagination' => ['totalPages' => ...]]
    }
}

// Usage:
// $client = new KuvolaClient("kv_live_...");
// $result = $client->v2ListMarkets(['pageSize' => 25]);