API Reference

概述

介绍

WARMKEY API 是一个 RESTful 服务，专为安全高效的支付网关操作而构建。身份验证通过 API 密钥进行，确保所有请求都经过验证和授权。每个用户都会收到一对凭证：一个 API 密钥和一个 RSA 私钥，类似于用户名和密码。重要的是，WARMKEY 绝不会存储用户的 RSA 私钥。

  • API密钥放置在请求体的头部参数中。
  • RSA 私钥用于生成签名，从而确保请求的完整性和真实性。

通过利用这些密钥，WARMKEY 确保了强大的安全机制，防止未经授权的访问，同时提供灵活且可扩展的 API 来处理与支付相关的操作。

基本 URL

https://api.warmkey.finance

基本 URL 是 WARMKEY 用于接收 API 请求的主要域名。每个 API 端点都指定其唯一的 URL 路径，完整的 API 端点 URL 由基本 URL 与相应的 URL 路径组合而成。

例如，完整的 API 请求 URL 结构如下：

{基本 URL} + {端点 URL 路径}

这种结构使 WARMKEY 能够高效地组织和处理不同的 API 请求，确保每个服务调用都能到达相应的端点。所有请求都必须以基本 URL 开头，后跟与所需功能对应的特定路径。

请求

requestBody.header

这些标头是必须包含的，并且位于请求正文中，而不是 HTTP 标头中。

参数类型/格式描述
api_keystring从https://secure.warmkey.finance门户获取您的 API 密钥及其关联的 RSA 私钥。
signaturestring / hex由 $headers 和 $payload 连接生成的 64 字节签名。
noncestring / milliseconds13位数字

签名生成

使用 RSA 私钥 生成签名，并将包含在标头的 signature 参数中。


$signature_data = json_encode(["header"=>$headers, "payload"=>$payload]);
$to_sign = hash('sha256', $signature_data, true);
$your_private_key_pem = <<EOD
-----BEGIN PRIVATE KEY-----
MIIBVwIBADANBgkqhkiG9w0BAQEFAASCAUEwggE9AgEAAkEA1eerGN7aInrV0myN
5RYAVL58JsUQCdkIUYDLoupVLnhO8uw0DD5ooNwd8gT8KJU0UzKSpRN+sjSwutD3
ZMrvAQIDAQABAkEA1VLwmKIPa5mTSwLF1DTH6bv6tvOK1jdjC11mOLh4cRjoEw83
FzwSfuWlGyFGdir5PE5SK/1D8nZ41h8bnw9pAQIhAP/AQKUYlha+t7gGstFc+J6Z
9ZgoxT44ngyF5dE/4+FRAiEA1hz8Rpwwrm8pwp+kdho8guTwozmpvMrQYdRufjag
RrECIQCTtZrgf3m3+0CqlZvTlam2GF+jGPEKhbKqsu7P0uGvcQIhAIr1MtEMqxd6
M6sI+q5fZqg4tufoE33gTo8/VBp7j1dxAiEAsvhkqXu0AWvkJxVrCfQWiv5RMxAL
LXPLNzdej9IFEns=
-----END PRIVATE KEY-----
EOD;
$private_key = openssl_pkey_get_private($your_private_key_pem);
openssl_sign($to_sign, $signature, $private_key, OPENSSL_ALGO_SHA256);

Nonce

这是为了防止重放攻击，并设定一定的容错率。用户只需输入当前的毫秒数即可。

requestBody.payload

  • 每个 API 端点都有其独特的有效负载设计。
  • 所有参数值均为字符串类型，并且 API 端点中也指定了格式类型。我们这样设计有两个原因。
    • 为了让双方容易生成一致的签名。
    • 在加密货币领域，金额可能非常大也可能非常小，字符串更适合处理这种情况。

代码示例

<?php

// Define the API credentials
$api_key = '<YOUR API KEY>'; // Replace with your API Key
$api_url = 'https://api.warmkey.finance'; // base url
$api_path = '/paymentV1/queryLog'; // path to reach getConversionRate

// Create a nonce (e.g, current miliseconds to ensure uniqueness)
$nonce = (string)round(microtime(true) * 1000);

// Define the payload (getConversionRate has empty payload)
$payload = [
	'log_id' => 1
];

// Generate the signature
$headers = [
    'api_key' => $api_key,
    'nonce' => $nonce
];

$signature_data = json_encode(["header"=>$headers, "payload"=>$payload]);
$to_sign = hash('sha256', $signature_data, true);
$your_private_key_pem = "<YOUR PRIVATE KEY IN PEM FORMAT>";
$private_key = openssl_pkey_get_private($your_private_key_pem);
openssl_sign($to_sign, $signature, $private_key, OPENSSL_ALGO_SHA256);
$headers["signature"] = bin2hex($signature);

$request_body = ["header"=>$headers, "payload"=>$payload];

// Prepare the cURL request
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $api_url.$api_path);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_body));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the cURL request and get the response
$response = curl_exec($ch);

// Handle errors
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'Response:' . $response;
}

// Close the cURL session
curl_close($ch);
?>

响应与错误

  • 响应以 JSON 文档形式呈现。
  • WARMKEY 不依赖于 HTTP 异常处理代码。

必填参数

参数类型/格式描述
codestring / uint64如果代码不等于 100，则出错。
messagestring如果代码不等于 100，则显示错误消息。
resultgeneric每个API接口都有其自身的结果设计。
noncestring / milliseconds13位数字表示毫秒。
signaturestring / hex使用 hash256( json_encode['code'=>..., 'message'=>..., 'result'=> ..., 'nonce'=>...] ) 生成 64 字节签名。

例如，

{
	"code": "100",
	"message": "Success",
	"result": ["... some value ..."]
}

成功响应

代码信息
100成功

错误响应

代码 > 100。

代码信息
101签名无效
102WarmKey 正在维护中
103API 密钥无效
104随机值无效
105API 速率限制已超出
106API 方式无效
107该API方式正在维护中
108参数不完整
109参数格式无效
110网络无效
111地址格式无效
112重复的Unique Id
113代币符号无效
114未完成的提现设置
115无法创建提现请求
116未找到提款
117未找到存款 (001)
118未找到存款 (002)
119未经授权的访问
202暂未付款
290参数无效
291未找到可用的代币 (001)
292未找到可用的代币 (002)
293地址路径无效