Billing API Quickstart
What is the Billing API
The Billing API lets you manage your Kirha account balance, whitelist addresses, and top up credits with crypto. It is HTTP-only, there is no SDK wrapper yet.
- Base URL:
https://api.kirha.com/billing/v1 - Requests and responses use
application/json
Authentication
All Billing API calls require an Authorization: Bearer <token> header.
Authorization: Bearer <your_api_key>Get your balance
curl -X GET "https://api.kirha.com/billing/v1/account/balance" \
-H "Authorization: Bearer <your_api_key>"{
"balance": 1200,
"subscription_balance": 400,
"top_up_balance": 800
}Top up credits with crypto
POST /account/topup initiates a purchase and quotes the exact on-chain payment expected. The flow completes once the on-chain transfer is mined and confirmed with POST /account/topup/{id}/complete.
Initiate the top-up
curl -X POST "https://api.kirha.com/billing/v1/account/topup" \
-H "Authorization: Bearer <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"type": "crypto",
"currency_id": "eth",
"credits": 1000
}'The response includes the quoted amount, currency_id, and destination_address.
Send the blockchain transfer
Transfer the quoted amount to the Kirha treasury address out-of-band. The invoice stays in requested status until the transaction is mined.
Confirm completion
curl -X POST "https://api.kirha.com/billing/v1/account/topup/{id}/complete" \
-H "Authorization: Bearer <your_api_key>" \
-H "Content-Type: application/json" \
-d '{ "transaction_hash": "0xpaymenthash" }'Successful validation moves the purchased credits into your top-up balance.
Error model
Failures return a normalized payload:
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable summary",
"details": {}
}
}Common codes: INVALID_REQUEST, UNAUTHORIZED, ACCOUNT_NOT_FOUND, CURRENCY_NOT_SUPPORTED, PAYMENT_NOT_COMPLETED, PAYMENT_ALREADY_USED, INTERNAL_ERROR.
API Reference
GET /account/balance
No parameters. Returns balance, subscription_balance, and top_up_balance.
POST /account/topup
Prop
Type
POST /account/topup/{id}/complete
Prop
Type