单钱包 API · 客户端 Demo

PHP

依赖：无（内置 curl）。

<?php
// client.php — PetaX single-wallet-api 客户端 Demo（PHP，调用 PetaX 服务 API）
// 依赖：无（使用内置 curl）
// 仅用于 Demo：这里演示请求构造和基础非 2xx 错误处理；生产客户端可按需补充 token 管理、重试/超时、结构化日志和金额精度处理。
// 三项配置来自接入环境：API_BASE_URL 是 PetaX 域名，SW_PATH_PREFIX 是单钱包路径前缀，BEARER_TOKEN 是调用 PetaX Service API 的 token。

$API_BASE_URL   = getenv('PETAX_API_BASE_URL') ?: 'https://your-petax-host.example';
$SW_PATH_PREFIX = getenv('PETAX_SW_PATH_PREFIX') ?: '/api/0857-sw';
$BEARER_TOKEN   = getenv('PETAX_BEARER_TOKEN') ?: '';

// 统一封装出站请求：拼 URL、带 Authorization、按需序列化 JSON body，并把非 2xx 响应转成异常。
function petax_request(string $method, string $path, ?array $query = null, ?array $body = null): array {
    global $API_BASE_URL, $SW_PATH_PREFIX, $BEARER_TOKEN;
    $url = $API_BASE_URL . $SW_PATH_PREFIX . $path;
    if ($query) {
        // 过滤 null 查询参数，避免把未使用的筛选条件拼进 URL。
        $url .= '?' . http_build_query(array_filter($query, fn($v) => $v !== null));
    }
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $BEARER_TOKEN,
            'Content-Type: application/json',
        ],
    ]);
    if ($body !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    // 这里不调用 curl_close($ch)：PHP 8.0 起它已是空操作，PHP 8.5 起会触发弃用警告。
    if ($status < 200 || $status >= 300) {
        throw new RuntimeException("PetaX API error ($status): $raw");
    }
    return ['status' => $status, 'body' => $raw === '' ? null : json_decode($raw, true)];
}

// 端点 8：通知 PetaX 钱包余额已变化。官方文档该接口返回空字符串，所以 demo 只关心 HTTP 是否成功。
function notify_change_balance(float $balance, string $ccy, string $username): void {
    petax_request('POST', '/a/sw/wallets/notify-change-balance', null, [
        'balance' => $balance, 'ccy' => $ccy, 'username' => $username,
    ]);
}

// 端点 9：按官方字段查询交易流水；时间、id、refId 都作为可选筛选条件传给 PetaX。
function list_transactions(?string $createdAtGte = null, ?string $createdAtLt = null, ?string $id = null, ?string $refId = null, int $page = 1, int $size = 10): array {
    $res = petax_request('GET', '/a/sw/transactions', [
        'createdAtGte' => $createdAtGte, 'createdAtLt' => $createdAtLt,
        'id' => $id, 'refId' => $refId, 'page' => $page, 'size' => $size,
    ]);
    return $res['body'];
}

// 端点 10：通过 PetaX 返回的交易 id 查询单笔流水。
function get_transaction_by_id(string $id): array {
    $res = petax_request('GET', "/a/sw/transactions/$id");
    return $res['body'];
}