nuBlock Business API

Complete API reference for viewing enabled currencies, sending payments, and swapping cross-chain currencies.

Base URL
https://apipayments.nublock.xyz/api/business/v1
GET/enabledCurrencies?businessId=:businessId
Get Enabled Currencies
Retrieve the list of currencies enabled for a specific business account. Returns all supported currencies with their _id, name, symbol, decimal and price.

Parameters

The unique identifier for the account

Example Request

// Get enabled currencies for an account
const response = await fetch(
  'https://apipayments.nublock.xyz/api/business/v1/enabledCurrencies?businessId=:businessId',
  {
    method: 'GET',
    headers: { 
      'Content-Type': 'application/json'
    }
  }
);

const response = await response.json();
// Response: { _id, name, symbol, decimals, price }
console.log(response.data);
javascript
POST/
Send Payment
Initiate a new payment transfer to a recipient wallet address. Supports all enabled currencies.

Request Body

Example Request

// Send a payment
const response = await fetch(
  '',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 1500,
      currencyId: '67ceda3edaadb',
      user_address: '0xabcd...ef12',
      recipientWallet: '0xabcd...ef12',
      apiKey: '68c8ed6be1d147a
    })
  }
);

const payment = await response.json();
console.log(payment.success, payment.data.to, payment.data.data, payment.data.value, payment.data.approve);
// When approve address is provided you need to approve it for token transfer
javascript
POST/
Swap
Initiate a new swap request for a wallet address. Supports enabled currencies.

Request Body

Example Request

// Swap
const response = await fetch(
  '',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 1500,
      inputCurrencyId: '67ceda3edaadb',
      outputCurrencyId: '67ceda3edaadb',
      user_address: '0xabcd...ef12',
      apiKey: '68c8ed6be1d147a
    })
  }
);

const swap = await response.json();
console.log(swap.success, swap.data.to, swap.data.data, swap.data.value, swap.data.approve);
// When approve address is provided you need to approve it for token transfer
javascript
Widget/
Checkout Widget
Allows you to embed nuBlock payment gateway on your website store.

The Checkout Widget allows you to embed a secure checkout experience directly into your website using a simple JavaScript integration.

Prerequisites

  • Valid API Key
  • Basic knowledge of HTML & JavaScript
  • Access to edit your website's source code

Step 1: Include the Script

Add the widget script before the closing </body> tag.

<script src="https://auth.nublock.xyz/assets/js/pages/checkout-widget.js?businessId=:apiKey"></script>
javascript

Step 2: Add Button Container

Create a container where the checkout button will be rendered.

<div id="my_checkout" data-checkout-widget 
      data-amount="49.99"    
      data-currency="USD"    
      data-name="John Doe"    
      data-email="john@example.com" 
      data-phone="+1234567890"  
      data-account-id="API KEY"></div>
javascript

Step 3: Initiaze nuBlock Widget

window.nuBlockInitWidget()
javascript

Step 4: Read Transaction Status

window.addEventListener("message", handleMessage);

const handleMessage = (event: MessageEvent) => {
      // ✅ Only accept messages from popup
    if (!event.data || !event.data.status) return;

    if (event.data.status === "success") {        
      console.log("Success:", event.data);
    } else if (event.data.status === "failure") {
      alert("Payment Failed!");
      console.error("Failure:", event.data);
    }
  };
javascript
Demo Link : https://demo.checkout.nublock.xyz/
Source Code : https://gitlab.com/nuBlock/checkout_example_products_shoppingcart
Rate Limits & Fees
Understand API rate limiting policies, platform fees, and best practices for handling rate limit errors.

Overview

The nuBlock Business API implements rate limiting to ensure fair usage and maintain service stability. Rate limits are applied on a per-account basis.

Platform Fees

Transaction Fee15 bps

A platform fee of 15 basis points (0.15%) is applied to each transaction. This fee is automatically deducted from the transaction amount.

Example: For a $1,000 transaction, the platform fee would be $1.50

Rate Limit Tiers

StandardDefault tier
20 requests/min

Suitable for most integrations

Response Headers

Every API response includes headers with rate limit information:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed per minute
X-RateLimit-RemainingNumber of requests remaining in current window
X-RateLimit-ResetUnix timestamp when the rate limit resets

Handling Rate Limit Errors

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}

Best Practice: Implement exponential backoff when retrying requests after receiving a 429 response.

Infrastructure

White-label infrastructure for banks — username-to-wallet identity, real-time webhooks, and Just-In-Time card payment rails. Linked to the same nuBlock account as the Business API (enabled currencies and fees from the portal Infrastructure page).

Authentication
Every /api/banking/v1 endpoint requires two keys from the same business account.
Infrastructure API Key

Secret nu_sk_live_* generated in the portal Infrastructure page.

Authorization: Bearer …

or header: x-api-key

Platform API Key

Your business account ID — same key used for the Business API.

x-platform-key: YOUR_ID

Example Request

// Both keys are required on every Infrastructure API request
const response = await fetch(
  'https://apipayments.nublock.xyz/api/banking/v1/config',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer nu_sk_live_xxxxxxxx',
      'x-platform-key': 'YOUR_PLATFORM_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data);
javascript

401 — Missing or invalid key

403 PLATFORM_KEY_MISMATCH — Platform key does not match the Infrastructure key owner

Infrastructure Base URL
https://apipayments.nublock.xyz/api/banking/v1
GET/config
Get Config & Enabled Currencies
Returns settlement defaults, conversion fee, and enabled stablecoins from your Currency panel.

Secret key from the Infrastructure page in the portal

Send as x-platform-key header on every request

Example Request

const response = await fetch(
  'https://apipayments.nublock.xyz/api/banking/v1/config',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer nu_sk_live_xxxxxxxx',
      'x-platform-key': 'YOUR_PLATFORM_API_KEY'
    }
  }
);

const { data } = await response.json();
// data.enabled_currencies, data.settlement_asset, data.default_fee_percent
console.log(data);
javascript
POST/wallets/create
Create Wallet
Map a human-readable username to a deterministic ERC-4337 Smart Account address.

Secret key from the Infrastructure page in the portal

Send as x-platform-key header on every request

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/wallets/create', {
  method: 'POST',
  headers: { Authorization: 'Bearer …', 'x-platform-key': '…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ desired_username: 'alice', user_id: 'cust_12345', initial_balance: 500 })
})
javascript
GET/wallets/resolve/:username
Resolve Username
Resolve a username to its on-chain Smart Account address.

Uses username from Create Wallet field above.

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/wallets/resolve/alice', { headers: { Authorization: 'Bearer …', 'x-platform-key': '…' } })
javascript
POST/wallets/transaction/sign
Relay Transaction
Relay a signed UserOperation via the Bundler (ERC-4337). Gasless via Paymaster.

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/wallets/transaction/sign', {
  method: 'POST',
  headers: { Authorization: 'Bearer …', 'x-platform-key': '…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'alice', userOp: { sender: '0x...', nonce: 1 } })
})
javascript
POST/wallets/fund
Fund Wallet (Sandbox)
Top up a wallet balance for sandbox testing of card authorizations.

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/wallets/fund', {
  method: 'POST',
  body: JSON.stringify({ username: 'alice', amount: 100, target: 'both' })
})
javascript
GET/wallets
List Wallets
List all Smart Account wallets registered for your bank.

Secret key from the Infrastructure page in the portal

Send as x-platform-key header on every request

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/wallets', { headers: { Authorization: 'Bearer …', 'x-platform-key': '…' } })
javascript
POST/webhooks/subscribe
Subscribe to Events
Register an HTTPS endpoint for real-time events. Payloads are signed with HMAC-SHA256 in X-Nublock-Signature.

Secret key from the Infrastructure page in the portal

Send as x-platform-key header on every request

Subscribes to: wallet.balance.updated, wallet.payment.received, payment.received, …

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/webhooks/subscribe', {
  method: 'POST',
  body: JSON.stringify({
    url: 'https://acme.bank/hooks/nublock',
    event_types: ['swap.executed', 'card.authorized']
  })
})
javascript
GET/webhooks
List Subscriptions
List webhook subscriptions and last delivery status.

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/webhooks', { headers: { Authorization: 'Bearer …', 'x-platform-key': '…' } })
javascript
GET/webhooks/events
List Event Types
Returns all supported webhook event type strings.
Supported: wallet.balance.updated, wallet.payment.received, payment.received, swap.executed, card.authorized, card.declined

Example Response

{
  "success": true,
  "data": [
    "wallet.balance.updated",
    "wallet.payment.received",
    "payment.received",
    "swap.executed",
    "card.authorized",
    "card.declined"
  ]
}
json
DELETE/webhooks/:id
Delete Subscription
Permanently remove a webhook subscription.

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/webhooks/SUBSCRIPTION_ID', { method: 'DELETE', headers: { Authorization: 'Bearer …', 'x-platform-key': '…' } })
javascript
POST/cards/authorize
Authorize Card (JIT)
Just-In-Time funding bridge at card swipe time. Checks balance, locks crypto, swaps to fiat, and approves in under 500ms.

Secret key from the Infrastructure page in the portal

Send as x-platform-key header on every request

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/cards/authorize', {
  method: 'POST',
  headers: { Authorization: 'Bearer …', 'x-platform-key': '…', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'alice',
    requested_fiat_amount: '50.00',
    currency: 'USD',
    balance_check_mode: 'hybrid'
  })
})
javascript
GET/cards/authorizations
List Authorizations
List recent card authorization decisions (approved and declined).

Example Request

fetch('https://apipayments.nublock.xyz/api/banking/v1/cards/authorizations?limit=50', {
  headers: { Authorization: 'Bearer …', 'x-platform-key': '…' }
})
javascript
GET/settlements/daily
Daily Settlement
Daily reconciliation ledger of stablecoin volume swapped into fiat for card clearings.

Secret key from the Infrastructure page in the portal

Send as x-platform-key header on every request

Example Request

const response = await fetch(
  'https://apipayments.nublock.xyz/api/banking/v1/settlements/daily?date=2026-06-08',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer nu_sk_live_xxxxxxxx',
      'x-platform-key': 'YOUR_PLATFORM_API_KEY'
    }
  }
);

const { data } = await response.json();
console.log(data.reconciliation_hash);
javascript
Infrastructure Rate Limits & Fees
Rate limiting and conversion fees for Infrastructure endpoints (card authorizations and general endpoints).

Card Conversion Fee

A liquidity conversion fee is applied on each card authorization when swapping stablecoin to fiat. Configured per bank via default_fee_percent in the portal (shared with Profile Vault, typically 0.10%).

Example: A $50.00 swipe debits ~50.05 USDC at 0.10% fee.

Rate Limit Tiers

General endpoints
600 req/min

Per Infrastructure API key

/cards/authorize
3,000 req/min

Higher limit for swipe-time calls

Response Headers

HeaderDescription
X-RateLimit-LimitMaximum requests allowed per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the limit resets

Rate Limit Errors

{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests"
}