SHKeeper 是一款开源的自托管加密货币支付处理器。它独特地既是网关，也是商户，使你能够无手续费和中介地接受各种加密货币的支付。
- 支持币种： BTC, ETH, USDT (ERC20/TRC20), LTC, DOGE 等主流加密货币。
- 核心特性：
-
- 0 平台手续费： 完全自托管，利润 100% 归商家。
- 全自动回调： 实时监听链上账单状态，自动更新订单状态。
- 高并发支持： 基于 Django + Python 架构，轻松应对海外节假日大流量。
- 隐私保护： 无需 KYC（实名认证），保护商家与用户的隐私安全。
-
- 部署环境： 支持 Ubuntu/Debian/CentOS (推荐使用 Docker 部署)。
-
🛠️ 部署环境及硬件要求 (Deployment Requirements)为了确保系统稳定运行并达到企业级高并发处理能力，建议使用以下环境：1. 操作系统 (Operating System)
-
- 推荐： Ubuntu 22.04 LTS 或 Debian 11/12 (最稳定的 Docker 运行环境)
- 兼容： CentOS 7/8/9, AlmaLinux, Rocky Linux
2. 核心引擎 (Core Engine) —— 推荐方式-
- Docker & Docker-compose: 系统已全量封装镜像，支持一键容器化部署，极大降低环境配置难度。
3. 硬件配置 (Minimum Hardware)-
- CPU: 1核 (推荐 2核及以上)
- 内存 (RAM): 最低 2GB (推荐 4GB，因为 Python 环境和数据库需要一定冗余)
- 硬盘 (Storage): 20GB 及以上可用空间
- 网络: 需具备海外网络环境（确保能稳定连接区块链节点及 API 接口）
4. 必备依赖 (Dependencies)- Python: 3.9+ (如不使用 Docker 部署需手动配置)
- Database: Redis & PostgreSQL (系统会自动在 Docker 容器内创建)
-
3. 特征
- 非监护
- 多币种
- 无交易手续费及第三方
- 直接加密支付
- 轻松嵌入支付按钮/二维码
- 能够设置汇率、佣金或费用
- 将多付款项计入余额
- 部分付款
- 将自动付款设置到冷钱包
- 隐私与安全性提升
- 没有KYC或AML
- 多重支付
4. 安装
在一个全新的服务器上安装k3s和helm（我在Ubuntu 22上测试过）：
# curl -sfL https://get.k3s.io | sh -
# mkdir /root/.kube && ln -s /etc/rancher/k3s/k3s.yaml /root/.kube/config
# curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
创建启用BTC、LTC、DOGE、XMR的Shkeeper图表配置文件：values.yaml
# cat << EOF > values.yaml
#
# General
#
storageClassName: local-path
#
# BTC and forks
#
btc:
enabled: true
ltc:
enabled: true
doge:
enabled: true
#
# Monero
#
monero:
enabled: true
fullnode:
enabled: true
EOF
安装Shkepeer头舵图：
# helm repo add vsys-host https://vsys-host.github.io/helm-charts
# helm repo add mittwald https://helm.mittwald.de
# helm repo update
# helm install kubernetes-secret-generator mittwald/kubernetes-secret-generator
# helm install -f values.yaml shkeeper vsys-host/shkeeper
登录Shkeeper：http://<ip>：5000/
安装自动SSL
安装证书管理器：
# helm repo add jetstack https://charts.jetstack.io
# helm install \
cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--version v1.9.1 \
--set installCRDs=true
创建CRD，用你自己的域名和邮箱地址替换“demo.shkeeper.io”和“[email protected]”：
cat << EOF > ssl.yaml
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: shkeeper-cert
namespace: shkeeper
spec:
commonName: demo.shkeeper.io
secretName: shkeeper-cert
dnsNames:
- demo.shkeeper.io
issuerRef:
name: letsencrypt-production
kind: ClusterIssuer
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-production
spec:
acme:
email: [email protected]
server: https://acme-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: your-own-very-secretive-key
solvers:
- http01:
ingress:
class: traefik
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: shkeeper
namespace: shkeeper
spec:
entryPoints:
- web
- websecure
routes:
- match: Host(`demo.shkeeper.io`)
kind: Rule
services:
- name: shkeeper
port: 5000
namespace: shkeeper
tls:
secretName: shkeeper-cert
EOF
应用CRDS：
# kubectl apply -f ssl.yaml
几分钟后，你的Shkeeper应该能在 https://<你的域名>上联系到，并且SSL是有效的。
比特币闪电的额外配置（仅限高级用户）
在 LNURL 端口 9000 启用启用 autossl 的 Ingress：
cat << EOF > /var/lib/rancher/k3s/server/manifests/traefik-config.yaml
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
name: traefik
namespace: kube-system
spec:
valuesContent: |-
additionalArguments:
- "[email protected]"
- "--certificatesresolvers.default.acme.storage=/data/acme.json"
- "--certificatesresolvers.default.acme.httpchallenge.entrypoint=web"
ports:
lnurl:
port: 9000
exposedPort: 9000
expose:
default: true
EOF
端口应该公开，LNURL才能正常工作。9000
编辑以补充，在顶层。它将用于生成LNURL，并用于Lightning的点对点通信。values.yamldomain:external_ip:domainexternal_ip
#
# General
#
storageClassName: local-path
external_ip: 1.2.3.4
domain: my-shkeeper.example.com
...
5. 开发
5.1. 支付流程
通过SHKeeper接受付款的流程如下： 安装好SHKeeper并在管理面板看到活跃的钱包后，你可以开始配置商店以支持SHKeeper。SHKeeper 运行在基于发票的系统上，每张发票对应相应加密货币的唯一地址。这可以让你识别出付款的客户。
创建发票需要在头部传递 ，你还需要知道加密货币名称来构成请求的端点。X-Shkeeper-Api-Key
首先，你需要从SHKeeper获取可用于发票的加密货币列表（这些是在线的，管理面板中没有被禁用的）。
为此，使用端点 。该端点无需授权。检索到的列表可以显示给客户，以便选择想要的加密货币进行支付。/api/v1/crypto
接着，使用端点为所选加密货币创建发票。在你已经知道系统中的唯一性时，应该在SHKeeper中创建发票，且仅针对客户选择的加密货币（不要立即为所有从SHKeeper收到的加密货币创建发票，因为这会产生多余地址，之后不会再用到）。SHKeeper 中的发票是独一无二的，在 SHKeeper 系统中会为 一个 。客户可以改变主意，生成另一种加密货币的地址;在这种情况下，只需像往常一样为新加密货币创建发票，SHKeeper会自动更新已创建的发票中的信息，并提供新的付款地址。如果客户支付到之前生成的地址，SHKeeper将处理该付款，并会收到关于该付款的回拨通知，因为SHKeeper保存了客户生成的所有地址。对于每种加密货币，用户都会获得一个与其特定（invoice_id）关联的唯一加密货币地址。即使你再次向SHKeeper请求创建同一张发票，这个地址依然保持不变。/api/v1/{crypto_name}/payment_requestorder_id /invoice_idexternal_idorder_id
在 SHKeeper 创建发票时，提供 以指示 SHKeeper 在收到与该发票相关的交易时应在哪里发送通知（回调）。当收到对应发票的交易时，SHKeeper 会更新发票状态。SHKeeper 中的发票可以处于以下状态之一：未支付、部分付款、已支付、超额支付。你会在回电中收到发票的当前状态。callback_url
- 未支付：新创建发票的初始状态，且尚未完成任何交易。
- 部分付款：已收到交易但金额不足以全额支付的发票状态。
- 付费：SHKeeper上的全额支付发票。您可以通过钱包中的相应设置来影响发票何时被视为全额支付的门槛。
- 超额支付：客户在交易中汇入总金额超过发票总额时的状态。你可以通过钱包中的相应设置来影响发票被认为多付的阈值。
在为门店开发付款模块时，你可以考虑SHKeeper发票状态，但在使用回拨价值时要注意。 默认情况下，在添加交易并计算法币金额时，SHKeeper 使用发票创建或更新时生效的加密货币汇率。不过，你可以通过在钱包设置中配置相关字段来调整这种行为。overpaid_fiat
如果你将“重新计算发票利率”设置为非0的值，那么在发票在指定时间后支付时，汇率将是交易入账时的汇率。在 SHKeeper 创建发票时，会返回包含该字段的对象，方便你告诉客户当前汇率将被保留多久。recalculate_after
静态地址模式（高级）
对于需要每位客户永久存款地址的企业（如交易所、托管流、定期存款），SHKeeper 支持“静态地址”使用模式，且不改变核心发票机制：
-
为每个客户和每枚币创建一个“大型”可重复使用的发票。设定一个有意较高的目标金额，确保发票在正常运营时永远不会达到“全额支付”状态。这样你就可以重复使用同一个地址，用于同一客户的多笔存款。
-
通过重复使用同一张发票，保持地址不变。SHKeeper 中的每张发票都映射到一个独特的区块链地址。通过重复使用该发票，您可以保持客户的存款地址不变。
-
通过“之后重新计算发票费率”来控制价格暴露。设定最短的重新计算周期（例如1小时），这样法币/加密货币的转换快照会在你的节奏时被刷新。在配置期间内，费率保持固定;该快照过期后，下一批交易将自动使用更新后的速率快照。
注释与注意事项
- 这种方法既保持了静态存款地址，又通过重新计算窗口保持利率处理的可预测性。
- 标准发票阈值（低于/多付的期限）和确认仍然适用。
- 会计和对账仍然以发票为中心：你通过为每个客户/币设立专属发票，将多笔存款归属于同一客户。
5.2. API
5.2.1. 认证
5.2.1.1. ApiKey
进入SHKeeper，查看或生成新的API密钥。
每个钱包的API密钥都是一样的，所以你可以在任何一个钱包上执行这个操作。
SHKeeper 支持用户通过用户生成的 API 密钥进行身份验证和授权。将API密钥作为头值发送给授权，格式为：X-Shkeeper-Api-Key {API Key}
唯一不需要授权的请求是获取活跃加密货币列表的请求：GET /api/v1/crypto
5.2.1.2. 基础版（仅用于支付）
SHKeeper 仅支持通过基础 HTTP 认证方案对支付相关 API 调用进行身份验证和授权。发送用户和密码，格式为 base64 编码。用于支付相关端点必须使用这种认证。Basic {base64(username:password)}
5.2.1.3. 支持的法定货币
SHKeeper 始终支持 和 。USDEUR
你可以用环境变量添加更多法定货币。EXTRA_CURRENCIES
示例：
EXTRA_CURRENCIES=""->USD,EUREXTRA_CURRENCIES="TRY,CAD"->USD, , ,EURTRYCAD
5.2.2. 检索可用加密货币列表
端点：授权：无需授权。HTTP 请求方法：获取卷发示例请求：/api/v1/crypto
curl --location --request GET
'https://demo.shkeeper.io/api/v1/crypto'
成功回应：
{
"crypto": [
"BNB",
"ETH",
...
],
"crypto_list": [
{
"display_name": "BNB",
"name": "BNB"
},
{
"display_name": "Ethereum",
"name": "ETH"
},
...
],
"status": "success"
}
使用该数组;该数组仅存在于向下兼容。在阵列中：crypto_listcryptocrypto_list
name用于为发票创建请求形成端点，display_name是加密货币的人类可读格式。
注释与注意事项
SHKeeper 使用短寿命的内存内 TTL 缓存来加速 /crypto 端点。关于可用加密货币和节点状态的缓存数据可能略有过时（最多可达60秒）。在多进程部署中，每个实例保留自己的缓存，这可能导致响应间存在细微差异。缓存减少了短期节点或网络的波动，但可能会短暂延迟反映实时状态变化。
5.2.3. 发票制作
端点：授权：ApiKey。HTTP 请求方法：带有以下格式的JSON对象的POST请求：/api/v1/<crypto_name>/payment_request
{
"external_id":<order_id>,
"fiat":"USD",
"amount":"<order_amount>",
"callback_url":"<callback_script_url>"
}
external_id：你店里的独特order_id或invoice_id。fiat：用于兑换的货币代码为ISO 4217格式。 并且默认启用;可用 启用额外货币。USDEUREXTRA_CURRENCIESamount：发票应在SHKeeper中创建的金额。callback_url：SHKeeper在发生与创建发票相关的交易时发送通知的URL。
SHKeeper 使用配对和作为发票识别器，并在下一次发票请求中重复使用时更新发票。卷发请求示例：external_idcallback_url
curl --location --request POST 'https://demo.shkeeper.io/api/v1/ETH/payment_request' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
--header 'Content-Type: application/json' \
--data-raw '{"external_id":107,"fiat":"USD","amount":"18.25","callback_url":"https://my-billing/callback.php"}'
成功示例回应：
{
"amount": "0.01080125",
"display_name": "Ethereum",
"exchange_rate": "3379.24",
"id": 61,
"recalculate_after": 0,
"status": "success",
"wallet": "0x8695f1a224e28adf362E6f8a8E695EDCc5D64960"
}
不可用的加密回复：
{
"message": "BTC payment gateway is unavailable",
"status": "error"
}
5.2.3.1 引用生成
端点：授权：ApiKey。HTTP 请求方法：带有以下格式的JSON对象的POST请求：/api/v1/<crypto_name>/quote
{
"fiat": "USD",
"amount": "100.00"
}
fiat：用于兑换的货币代码为ISO 4217格式。 并且默认启用;可用 启用额外货币。USDEUREXTRA_CURRENCIESamount：加密货币报价应生成的金额。
该端点返回等值的加密货币金额和兑换时使用的汇率。它不生成发票，主要用于信息参考（例如，向用户展示在生成真实发票前需要支付多少加密货币）。
卷发请求示例：
curl --location --request POST 'https://demo.shkeeper.io/api/v1/ETH/quote' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
--header 'Content-Type: application/json' \
--data-raw '{"fiat":"USD","amount":"100.00"}'
成功示例回应：
{
"crypto_amount": "0.02981237",
"exchange_rate": "3353.26",
"status": "success"
}
不可用的加密回复：
{
"message": "BTC payment gateway is unavailable",
"status": "error"
}
5.2.4. 检索已创建地址
Endpoint: Authorization: ApiKey. HTTP request method: GET Example Curl request:/api/v1/<crypto_name>/addresses
curl --location --request GET 'https://demo.shkeeper.io/api/v1/ETH-USDC/addresses' \
--header 'X-Shkeeper-Api-Key: nApijGv8djih7ozY'
Successful Response:
{
"addresses": [
"0x0A71f4741DcaD3C06AA51eE6cF0E22675507d0d0",
…
"0x8695f1a224e28adf362E6f8a8E695EDCc5D64960"
],
"status": "success"
}
5.2.5. 按地址检索交易
端点：授权：ApiKey。HTTP 请求方法：GET 卷发示例：/api/v1/transactions/<crypto_name>/<addr>
curl --location --request GET 'https://demo.shkeeper.io/api/v1/transactions/ETH/0xDCA83F12D963c7233E939a32e31aD758C7cCF307' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY'
成功应对：
{
"status": "success",
"transactions": [
{
"addr": "0xDCA83F12D963c7233E939a32e31aD758C7cCF307",
"amount": "0.0001000000",
"crypto": "ETH",
"status": "CONFIRMED",
"txid": "0xbcf68720db79454f40b2acf6bfb18897d497ab4d8bc9faf243c859d14d5d6b66"
}
]
}
未找到回复：
{
"status": "success",
"transactions": []
}
5.2.6. 按external_id检索信息
端点：授权：ApiKey。HTTP 请求方法：GET 卷发示例：/api/v1/invoices/<external_id>
curl --location --request GET 'https://demo.shkeeper.io/api/v1/invoices/107' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY'
成功应对：
{
"invoices": [
{
"amount_fiat": "18.2500000000",
"balance_fiat": "0E-10",
"external_id": "107",
"fiat": "USD",
"status": "UNPAID",
"txs": []
}
],
"status": "success"
}
未找到回复：
{
"invoices": [],
"status": "success"
}
5.2.7. 通过 transaction_id 和 external_id 检索信息
端点：授权：ApiKey。HTTP 请求方法：GET 卷发示例：/api/v1/tx-info/<tx_id>/<external_id>
curl --location --request GET 'https://demo.shkeeper.io/api/v1/tx-info/0xbcf68720db79454f40b2acf6bfb18897d497ab4d8bc9faf243c859d14d5d6b66/240' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY'
成功应对：
{
"info": {
"addr": "0xDCA83F12D963c7233E939a32e31aD758C7cCF307",
"amount": "0.295503",
"crypto": "ETH"
},
"status": "success"
}
未找到回复：
{
"info": {},
"status": "success"
}
5.2.8. 钱包加密（通过API输入decryption_key）
端点：授权：ApiKey。HTTP 请求方法：带有以下格式表单数据主体的POST请求：/api/v1/decryption-key
key=<decryption_key>
卷发示例：
curl --location --request POST 'https://demo.shkeeper.io/api/v1/decryption-key' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
--form 'key="asdfasfasgasgasgasgdeagweg"'
成功解密响应：
{
"status": "success"
}
成功响应（无需解密）：
{
"message": "Decryption key was already entered",
"status": "success"
}
错误回复：
{
"message": "Decryption key is required",
"status": "error"
}
{
"message": "Invalid decryption key",
"status": "error"
}
{
"message": "Wallet is not encrypted",
"status": "error"
}
5.2.9. 检索指标
端点：授权：使用度量凭证进行HTTP基础认证。度量凭证可以通过环境变量设置：。默认用户名/密码是 。HTTP 请求方法：获取卷发示例请求：/metricsMETRICS_USERNAME, METRICS_PASSWORDshkeeper/shkeeper
curl --location --request GET 'https://demo.shkeeper.io/metrics' \
--header 'Authorization: Basic c2hrZWVwZXI6c2hrZWVwZXI='
成功应对：
# HELP geth_last_release_info Version of the latest release from https://github.com/ethereum/go-ethereum/releases
# TYPE geth_last_release_info gauge
geth_last_release_info{name="Bothros (v1.14.5)",published_at="2024-06-06T13:41:53Z",tag_name="v1.14.5",version="1.14.5"} 1.0
# HELP prysm_last_release_info Version of the latest release from https://github.com/prysmaticlabs/prysm/releases
# TYPE prysm_last_release_info gauge
prysm_last_release_info{name="v5.0.4",published_at="2024-06-21T16:13:40Z",tag_name="v5.0.4",version="5.0.4"} 1.0
# HELP geth_fullnode_version_info Current geth version in use
# TYPE geth_fullnode_version_info gauge
geth_fullnode_version_info{version="1.14.6"} 1.0
# HELP prysm_fullnode_version_info Current prysm version in use
# TYPE prysm_fullnode_version_info gauge
prysm_fullnode_version_info 1.0
# HELP ethereum_fullnode_status Connection status to ethereum fullnode
# TYPE ethereum_fullnode_status gauge
ethereum_fullnode_status 1.0
# HELP ethereum_fullnode_last_block the Last block loaded to the fullnode
# TYPE ethereum_fullnode_last_block gauge
ethereum_fullnode_last_block 6.415394e+06
# HELP ethereum_wallet_last_block Last checked block
# TYPE ethereum_wallet_last_block gauge
ethereum_wallet_last_block 6.415392e+06
# HELP ethereum_fullnode_last_block_timestamp Last block timestamp loaded to the fullnode
# TYPE ethereum_fullnode_last_block_timestamp gauge
ethereum_fullnode_last_block_timestamp 1.722503064e+09
# HELP ethereum_wallet_last_block_timestamp Last checked block timestamp
# TYPE ethereum_wallet_last_block_timestamp gauge
ethereum_wallet_last_block_timestamp 1.72250304e+09
5.2.10. 支付
SHKeeper 允许你通过 API 进行支付。与支付相关的API调用与之前描述的有所不同，它们使用HTTP Basic Auth进行认证和授权，使用你的SHKeeper登录和密码。
支付流
- 创建支付任务（支付或多支付）
- 检查任务结果
创建派彩有两种方法：派彩和多重派彩，两者之间有一些差异。目前，以下加密货币不支持多重支付：XMR、BTC、LTC和DOGE。对于这些，你需要使用支付方式。
查看任务结果提交支付任务后，你应该投票查看任务状态：
- 待处理意味着任务正在进行中，目前还没有结果。
- 成功意味着任务完成，你会看到结果。
任务结果是一个对象数组，每个对象包含原始支付请求、交易状态（成功或错误）以及与支付相关的交易ID列表。如果传输状态恰好是错误，字段中会有错误的文本描述。message
5.2.11. 与支付相关的端点
5.2.11.1. 创建支付任务
端点：授权：HTTP 基本认证。HTTP 请求方法：带有以下格式的 JSON 对象的 POST 请求：/api/v1/<crypto_name>/payout
{
"amount": <amount_to_send>,
"destination": "<addr>",
"fee": "<transaction_fee>",
"callback_url": "<callback_url>", (OPTIONAL)
"external_id": "<external_id>" (OPTIONAL)
}
amount：要发的金额。destination：金额应寄到的地址。- 对于XRP，地址必须以X地址格式提供。X地址格式取代了在XRP账本上向多用户钱包（如交易所和托管服务）发送资金时使用独立目的标签的做法。
callback_url：（可选）SHKeeper在支付发生时发送通知的URL。external_id：（可选）你商店里的独特order_id。fee：交易费。- 即使是自动计算的加密货币，也必须明确说明这一点。
- 对于BTC，它以sat/vByte表示;对于长期护理和数字（DOGE），则是SAT/Byte。
- 对于 XMR，传递一个整数（1-4）以设置交易优先级：
- 1 – 无关紧要
- 2 – 普通
- 3 – 高架
- 4 – 优先级
- 对于其他加密货币，任何值都可以被传递;最优费用会自动计算并设定，该字段被忽略。
由于支付任务是异步过程，调用总是成功完成（除非缺少所需参数或 Basic 认证失败），返回 a，之后用于检查任务状态。task_id
卷发示例：
curl --location --request POST 'https://demo.shkeeper.io/api/v1/ETH-USDC/payout' \
--header 'Authorization: Basic nApijGv8djih7ozY' \
--header 'Content-Type: application/json' \
--data-raw '{"amount":107,"destination":"0xBD26e3512ce84F315e90E3FE75907bfbB5bD0c44","fee":"10", "callback_url": "https://my.payout.com/notification", "external_id": "435345534"}'
成功应对：
{"task_id":"b2a01bb0-8abe-403b-a3fa-8124c84bcf23", "external_id": "435345534"}
注： 如果在SHKeeper中启用enable_payout_callback，成功支付时会自动发送回调。 如果请求中提供了callback_url，SHKeeper 会将通知发送到该 URL。 回电通知示例：
{
"payout_id": 14,
"external_id": "435345534",
"tx_hash": "AF732D1D1254C97A77F4DD08553725E6ECC011CA6DCD12BC65FA1D8551E54E6D",
"status": "SUCCESS",
"amount": "2.0000000000",
"crypto": "XRP",
"amount_fiat": "4.364200000000000000",
"currency_fiat": "USD",
"timestamp": "2024-11-27T13:49:22"
}
5.2.11.2. 创建多重支付任务
端点：授权：HTTP 基本认证。HTTP 请求方法：带有以下格式的 JSON 对象的 POST 请求：/api/v1/<crypto_name>/multipayout
[{
"amount": <amount_to_send>,
"dest": "<addr>",
"callback_url": "<callback_url>", (OPTIONAL)
"external_id": "<external_id>" (OPTIONAL)
}]
发送XRP时，你可以选择性地传递一个。如果提供了地址，应以常规格式提供，SHKeeper 会自动将其转换为 X 地址格式。或者，您也可以手动将XRP地址转换为X地址格式并在字段中传递;在这种情况下，无需提供。dest_tagdestdest_tag
注： 如果在SHKeeper中启用enable_payout_callback，成功支付时会自动发送回调。 如果请求中提供了callback_url，SHKeeper 会将通知发送到该 URL。
卷发示例：
curl --location --request POST 'https://demo.shkeeper.io/api/v1/ETH-USDT/multipayout' \
--header 'Authorization: Basic nApijGv8djih7ozY' \
--header 'Content-Type: application/json' \
--data-raw '[{"dest":"0xE77895BAda700d663f033510f73f1E988CF55756","amount":"100", "external_id": "43234", "callback_url": "https://my.payout.com/notification"},{"dest":"0x7C4C7D3010d31329dd8244617C46e460E5EF8a6F","amount":"200.11", "external_id": "43235", "callback_url": "https://my.payout.com/notification"}]'
成功应对：
{
"task_id": "0471adec-5de5-4668-bc1d-e8e7729cb676",
"external_ids": [
"43234",
"43235"
]
}
注： external_ids数组的顺序保证与请求中支付项目的顺序完全一致。
错误回复：
{
"msg": "Bad destination address in {'dest': 'wrong_address', 'amount': '100'}",
"status": "error"
}
5.2.11.3. 检查任务状态
端点：授权：HTTP 基本认证。HTTP 请求方法：GET Curl 示例：/api/v1/<crypto_name>/task/<task_id>
curl --location --request GET 'https://demo.shkeeper.io/api/v1/ETH-USDC/task/7028c45b-0c88-483e-b703-dd455a361b2e' \
--header 'Authorization: Basic nApijGv8djih7ozY' \
--header 'Content-Type: application/json'
成功应对：
When the task is in progress:
{
"result": null,
"status": "PENDING"
}
任务完成后：
{
"result": [
{
"amount": "100",
"dest": "TGusXhweqkJ1aJftjmAfLqA1rfEWD4hSGZ",
"status": "success",
"txids": [
"4c32969220743644e3480d96e95a423d351049ac6296b8315103225709881ae3",
"da2996bae7a8a4d655a1288f8f4c79ce0aa3640e61f8ae8de08ae9c70c72d90d"
]
},
{
"amount": "200.11",
"dest": "TYtD9md7cHuB4P6kDd362jhcUGP7cJybF7",
"status": "success",
"txids": [
"e155f80221bf73a127ec8a9a5d1b6989edd38e7583e7747f128152833ff49090",
"0f999d988641395b38943d8a9c01581c19fcaa4dcdd4bb35f99e16510fdd10d6",
"8cbfe9131d406a1bcfca403f4318b9592e7c08c04ea9b20629f430762d4eb7a4",
"0036fbeadcb8cec278754f9fb7b18a3e9b57c71eb743115a8338d72b552a3dd4",
"d8972ac9c964adbc25486d2cfdf2de7b61c3f0ca7510aa7cddc832a9bccdf551"
]
}
],
"status": "SUCCESS"
}
失败反应：
{
"result": "Have not enough tokens on fee account, need 107 have 0",
"status": "FAILURE"
}
5.2.11.4. 获取加密货币余额信息
端点：授权：ApiKey。HTTP 请求方法：GET 卷发示例：/api/v1/<crypto_name>/balance
curl --location --request GET 'https://demo.shkeeper.io/api/v1/ETH/balance' \
--header 'X-Shkeeper-Api-Key: nApijGv8djih7ozY'
成功应对：
{
"amount_crypto":"0.0213590094",
"amount_fiat":"88.8201590493",
"display_name":"Ethereum",
"fiat":"USD",
"name":"ETH",
"rate":"4158.44000000",
"server_status":"Synced"
}
错误回复：
{
"message":"Crypto XRP is not enabled",
"status":"error"
}
5.2.11.5. 获取费用存款地址（如果加密货币支持）
端点：授权：ApiKey。HTTP 请求方法：GET 卷发示例：/api/v1/<crypto_name>/fee-deposit-address
curl --location --request GET 'https://demo.shkeeper.io/api/v1/ETH-USDT/fee-deposit-address' \
--header 'X-Shkeeper-Api-Key: nApijGv8djih7ozY'
成功应对：
{
"status": "success",
"crypto": "ETH-USDT",
"fee_deposit_address": "0x1234567890abcdef1234567890abcdef12345678"
}
错误回复：
{
"status": "error",
"message": "Crypto XYZ is not enabled"
}
5.2.11.6. 获取所有加密货币余额
终点：。授权：ApiKey。HTTP 请求方法：走。查询参数：（可选）。 包括——用逗号分隔的加密标识符列表，用于返回余额（例如，BTC、ETH、TRX）。不区分大小写。如果遗漏或空置，则返回所有启用加密货币的余额。未知或禁用的加密货币会被忽略。/api/v1/crypto/balances
卷发示例：
curl --location --request GET 'https://demo.shkeeper.io/api/v1/crypto/balances' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
--header 'Content-Type: application/json'
示例请求（加密货币子集）：
curl --location --request GET 'https://demo.shkeeper.io/api/v1/crypto/balances?includes=BTC,ETH'
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
--header 'Content-Type: application/json'
成功应对：
[
{
"name": "BTC",
"display_name": "Bitcoin",
"amount_crypto": "0.12345678",
"rate": "70616.07",
"fiat": "USD",
"amount_fiat": "8700.12",
"server_status": "online"
},
{
"name": "ETH",
"display_name": "Ethereum",
"amount_crypto": "1.2345",
"rate": "3015.50",
"fiat": "USD",
"amount_fiat": "3721.05",
"server_status": "online"
}
]
失败响应（包含无效/无有效加密请求）：
{
"status": "error",
"message": "No valid cryptos requested"
}
注释与注意事项
响应总是普通的JSON数组，没有额外的信封或元数据。 项目的顺序是确定性的： 如果包含 → 保留请求的顺序（仅有效条目） 如果包含不存在，→按姓名字母顺序排序。 部分失败（例如硬币的RPC错误）会导致该硬币被遗漏;不会引入新的误差字段。
SHKeeper 使用短寿命内存 TTL 缓存来加速 /crypto/balances 端点。关于可用加密货币和节点状态的缓存数据可能略有过时（最多可达60秒）。在多进程部署中，每个实例保留自己的缓存，这可能导致响应间存在细微差异。缓存减少了短期节点或网络的波动，但可能会短暂延迟反映实时状态变化。
端点：授权：ApiKey。HTTP 请求方法：去/api/v1/<crypto_name>/payout/status
查询参数：external_id为必填。分配了外部ID。用来查询其状态。
curl --location --request GET 'https://demo.shkeeper.io/api/v1/BTC/payout/status?external_id=abc123' \
--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
--header 'Content-Type: application/json'
成功应对：
{
"id": 114,
"external_id": "abc123",
"crypto": "BTC",
"status": "SUCCESS",
"amount": "100.50",
"destination": "0x1234567890abcdef...",
"txid": "0f999d988641395b38943d8a9c01581c19fcaa4dcdd4bb35f99e16510fdd10d6"
}
当支付正在进行时：
{
"id": 115,
"external_id": "abc124",
"crypto": "BTC",
"status": "IN_PROGRESS",
"amount": "50.25",
"destination": "0xabcdef1234567890",
"txid": null
}
失败反应：
{
"amount": "0.0500000000",
"crypto": "BTC",
"destination": "bcrt1qagdwааааааааlkzc3gn05q3t8v3qrw4saptql8nz8fvt7l",
"external_id": "dhjdrewds",
"id": 4,
"status": "FAIL",
"txid": null
}
5.3 接收回电
回调会在发票创建过程中发送到指定的机构。通常，这是一个脚本，接收来自SHKeeper的通知，进行验证并处理。callback_url
一旦 SHKeeper 收到付款，它会通过带有 JSON 编码主体和 HTTP 头部的 POST 请求向 发送付款通知，以便与你的系统进行认证。<callback_url>X-Shkeeper-Api-Key
如果支付通知被服务器成功处理，它应该返回HTTP代码。任何其他响应或连接失败都会使SHKeeper每60秒重新发送一次支付通知。202 Accepted
SHKeeper 会为每笔与发票相关的交易发送通知，即使发票已经处于支付/超付款状态。触发回调的交易会用字段标记。trigger
回调对象的结构：
{
"external_id": "1", // Invoice or Order ID in the external system
"crypto": "BTC", // cryptocurrency (provided during payment request creation)
"addr": "AAAAAAAAAAAAAA", // wallet address that receives payments
"fiat": "USD", // fiat currency (provided during payment request creation)
"balance_fiat": "100", // amount in fiat currency
"balance_crypto": "0.0025", // amount in cryptocurrency
"paid": true, // true if the payment request is fully paid
// false if only a partial payment is received
"status": "PAID", // PARTIAL - partial invoice payment
// PAID - full invoice payment
// OVERPAID - overpaid invoice payment
"transactions": [ // list of transactions related to the payment request
{
"txid": "ZZZZZZZZZZZZZZZZZZZ", // blockchain transaction ID
"date": "2022-04-01 11:22:33", // transaction date
"amount_crypto": "0.0025", // transaction amount in cryptocurrency
"amount_fiat": "50", // transaction amount in fiat currency
"trigger": false, // true if this transaction was the trigger for the payment notification
"crypto": "ETH-USDT" // transaction cryptocurrency
},
{
"txid": "CCCCCCCCCCCC", // blockchain transaction ID
"date": "2022-04-01 11:42:33", // transaction date
"amount_crypto": "0.0025", // transaction amount in cryptocurrency
"amount_fiat": "50", // transaction amount in fiat currency
"trigger": true, // true if this transaction was the trigger for the payment notification
"crypto": "ETH-USDT" // transaction cryptocurrency
}
],
"fee_percent": "2", // fee percentage added to the invoice amount
"overpaid_fiat": "0.00" // In case of overpayment, the overpaid amount will be shown here
}
回调示例：
{
"external_id": "147",
"crypto": "ETH-USDT",
"addr": "0x6f2Fc9D7205B7D9037dDE45B5f9e12B18EA07e27",
"fiat": "USD",
"balance_fiat": "7.80",
"balance_crypto": "7.80000000",
"paid": true,
"status": "PAID",
"transactions": [
{
"txid": "0x518a10b13a708fd11aa98db88c625dd45130db6656ba822600b01d0c53c85078",
"date": "2024-06-25 15:45:38",
"amount_crypto": "7.80000000",
"amount_fiat": "7.80",
"trigger": true,
"crypto": "ETH-USDT"
}
],
"fee_percent": "2",
"overpaid_fiat": "0.00"
}
更多其他优秀源码，请翻阅其他分类目录
