Developer API Reference
Welcome to the Valenix Developer Documentation. Our REST APIs and real-time streams allow you to integrate cryptocurrency payments—specifically USDT (BEP-20) on BNB Smart Chain—into any e-commerce store, mobile app, or backend service with instant finality and ultra-low fees (~$0.02).
https://valenix.co/api
Authentication
All merchant-scoped API endpoints require authentication using your merchant x-api-key passed in the HTTP request headers.
curl -X POST https://valenix.co/api/invoices \
-H "x-api-key: gw_live_your_merchant_api_key_here" \
-H "Content-Type: application/json"
Create Invoice
Generates a dedicated BIP-44 deposit address, QR code, and hosted checkout page for an order.
/api/invoices
Request Body
{
"amountExpected": "100.00",
"feeBearer": "MERCHANT", // or "CUSTOMER"
"webhookUrl": "https://your-store.com/api/crypto-webhook",
"expiryMinutes": 30
}
Response (201 Created)
{
"id": "16bcf1bd-f683-461e-9ece-d45a6760ad66",
"financials": {
"baseAmount": "100.00",
"feePercentage": "0.8%",
"feeAmount": "0.80",
"customerPays": "100.00",
"merchantCredits": "99.20",
"gatewayCommission": "0.80"
},
"tokenSymbol": "USDT",
"network": "BSC (testnet)",
"walletAddress": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
"status": "PENDING",
"checkoutUrl": "https://valenix.co/checkout/16bcf1bd-f683-461e-9ece-d45a6760ad66",
"qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgo..."
}
Real-Time Settlement Stream (SSE)
Subscribes to an open, persistent Server-Sent Events stream for instant payment state notifications (< 50ms latency).
/api/invoices/:id/stream
const eventSource = new EventSource("https://valenix.co/api/invoices/INVOICE_ID/stream");
eventSource.onmessage = (event) => {
const update = JSON.parse(event.data);
console.log("Invoice Status:", update.status, "Confirmations:", update.confirmations);
if (update.status === "CONFIRMED") {
alert("Payment Confirmed!");
}
};
Webhooks & HMAC-SHA256 Verification
When an invoice is detected or confirmed, Valenix sends an HTTP POST request to your webhookUrl with an X-Gateway-Signature header. Verify it using your secretKey:
// Node.js Webhook Verification Example
import crypto from 'crypto';
app.post('/api/crypto-webhook', (req, res) => {
const signature = req.headers['x-gateway-signature'];
const secretKey = process.env.GATEWAY_SECRET_KEY;
const expectedSignature = crypto
.createHmac('sha256', secretKey)
.update(JSON.stringify(req.body))
.digest('hex');
if (signature !== expectedSignature) {
return res.status(401).send('Invalid signature');
}
const { event, invoiceId, amountExpected, merchantCredited } = req.body;
if (event === 'invoice.confirmed') {
// Fulfill customer order in your database!
console.log(`Order paid! Credited: ${merchantCredited} USDT`);
}
res.sendStatus(200);
});
Integration SDKs
1. Node.js Drop-In Client
// valenix-client.js
import axios from 'axios';
export class ValenixClient {
constructor(apiKey, baseUrl = 'https://valenix.co/api') {
this.client = axios.create({
baseURL: baseUrl,
headers: { 'x-api-key': apiKey }
});
}
async createInvoice(amountExpected, webhookUrl = null) {
const res = await this.client.post('/invoices', { amountExpected, webhookUrl });
return res.data;
}
async getInvoice(invoiceId) {
const res = await this.client.get(`/invoices/${invoiceId}`);
return res.data;
}
}
// Usage:
const valenix = new ValenixClient('gw_live_your_api_key');
const invoice = await valenix.createInvoice('50.00');
console.log('Redirect customer to:', invoice.checkoutUrl);
2. Python SDK
# valenix.py
import requests
class ValenixClient:
def __init__(self, api_key, base_url="https://valenix.co/api"):
self.base_url = base_url
self.headers = {"x-api-key": api_key, "Content-Type": "application/json"}
def create_invoice(self, amount, webhook_url=None):
payload = {"amountExpected": str(amount), "webhookUrl": webhook_url}
response = requests.post(f"{self.base_url}/invoices", json=payload, headers=self.headers)
return response.json()
# Usage:
valenix = ValenixClient("gw_live_your_api_key")
inv = valenix.create_invoice(75.50)
print("Checkout URL:", inv["checkoutUrl"])
3. PHP / WooCommerce Client
<?php
function create_crypto_invoice($amount, $api_key) {
$url = 'https://valenix.co/api/invoices';
$data = array('amountExpected' => strval($amount));
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-key: ' . $api_key
));
$result = curl_exec($ch);
curl_close($ch);
return json_decode($result, true);
}
?>
Interactive API Playground
Test live invoice creation against your running server: