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).

âš¡ Base API URL: 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.

POST /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).

GET /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: