API Reference
nano-toolset HTTP API - base URL: http://127.0.0.1:3123
HTTP API
REST endpoints - this page
MCP / stdio
Model Context Protocol transport
Payment Pages
Payment request integration flow
Response Envelope
All endpoints return the same JSON wrapper:
{
"success": true | false,
"data": { /* endpoint-specific object */ } | null,
"error": { "error": "ERROR_CODE", "message": "Human-readable message" } | null
}
When success: true, check data. When success: false, check error.error for the error code.
Wallet
/wallet/balance
Retrieve the current wallet balance and pending incoming amount.
CURL
curl http://127.0.0.1:3123/wallet/balance
RESPONSE
{
"success": true,
"data": {
"account": "nano_1abc...",
"balance": "1.5",
"balance_raw": "1500000000000000000000000000000",
"pending": "0.0",
"pending_raw": "0"
},
"error": null
}
/wallet/send
Send Nano to any address. Sub-second finality, zero fees.
REQUEST BODY
{
"recipient_address": "nano_1abc...",
"amount": "0.001"
}
RESPONSE
{
"success": true,
"data": {
"amount": "0.001",
"recipient": "nano_1abc..."
},
"error": null
}
Payments
/payment/request
Create a payment request. Returns a unique transaction_id and a slightly adjusted amount for unique matching.
Important: The payer should send the exact amount returned in the response for reliable status matching.
REQUEST BODY
{
"receive_address": "nano_1abc...",
"amount": "1.5",
"redirect_url": "https://..." // optional
}
RESPONSE
{
"success": true,
"data": {
"receive_address": "nano_1abc...",
"amount": "1.500000054",
"transaction_id": "77df93b1-..."
},
"error": null
}
/payment/status/{transaction_id}
Check whether a payment request has been fulfilled.
CURL
curl http://127.0.0.1:3123/payment/status/77df93b1-...
RESPONSE
{
"success": true,
"data": {
"success": true,
"message": "Payment confirmed",
"transaction_id": "77df93b1-...",
"is_paid": true
},
"error": null
}
Credits
/credits
Get current credit balance and all available topup tiers with pricing.
{
"success": true,
"data": {
"credits": 850,
"current_credits_price_10": 0.1,
"current_credits_price_50": 0.5,
"current_credits_price_100": 1.0,
"current_credits_price_500": 5.0,
"current_credits_price_1000": 10.0,
"current_credits_price_5000": 50.0,
"current_credits_price_10000": 100.0,
"current_credits_price_50000": 500.0,
"current_credits_price_100000": 1000.0
},
"error": null
}
/credits/topup/{credits_amount}
Top up credits. The toolset automatically sends the required Nano payment and adds the credits to your account.
Valid amounts: 10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000
CURL
curl -X POST http://127.0.0.1:3123/credits/topup/100
RESPONSE
{
"success": true,
"data": {
"topped_up_credits": 100,
"new_credits_balance": 950
},
"error": null
}
Donate
/donate/{amount}
Donate Nano to the platform to support continued development.
CURL
curl -X POST http://127.0.0.1:3123/donate/0.1
RESPONSE
{
"success": true,
"data": {
"success": true,
"amount": "0.1",
"message": "Thank you for your donation!"
},
"error": null
}
Error Codes
When success: false, the error field contains a machine-readable code:
| Code | Description |
|---|---|
| INSUFFICIENT_FUNDS | Wallet does not have enough Nano for the requested send |
| INVALID_ADDRESS | Address must start with 'nano_' or 'xrb_' |
| INVALID_TRANSACTION_ID | The provided transaction ID is invalid or not found |
| INVALID_NUMBER_FORMAT | Amount is not a valid number. See also: INVALID_NEGATIVE_AMOUNT, TOO_MANY_DECIMAL_PLACES, INVALID_FRACTIONAL_PART, AMOUNT_TOO_LARGE |
| INVALID_CREDITS_AMOUNT | Credits topup amount must be one of: 10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000 |
| REQUEST_ERROR | Request to upstream ifenpay API failed. See also: PARSE_ERROR, INVALID_DATA |
Endpoint Summary
| Method | Path | Tool Name | Description |
|---|---|---|---|
| GET | /wallet/balance | wallet.balance | Get wallet balance and pending |
| POST | /wallet/send | wallet.send | Send Nano to an address |
| POST | /payment/request | payment.request | Create a payment request |
| GET | /payment/status/{transaction_id} | payment.status | Check payment status |
| GET | /credits | credits.get | Get credit balance and pricing |
| POST | /credits/topup/{credits_amount} | credits.topup | Top up credits (auto-pays Nano) |
| POST | /donate/{amount} | donate.send | Donate Nano to the platform |