Sign in Subscribe
Bitcoin Tutorials

The Easiest API for Accepting Bitcoin on Your Site

If you're looking to accept Bitcoin payments on your website with minimal friction, Blockonomics is one of the most developer-friendly and secure APIs out there. Here’s why it stands out and how you can get it up and running smoothly.

Why Blockonomics? No Custody, Direct to Wallet

Blockonomics is non-custodial. Payments are sent directly to your own wallet. You retain full control of your funds at all times.

Three Stages: Setup, Checkout, Monitor & Callback

a) Setup

  1. Add a wallet (e.g., Electrum for BTC).
  2. Create a store in the Blockonomics dashboard.
  3. Link the wallet to the store.
  4. Set your callback URL (webhook endpoint).

Tools like ngrok work well for local testing.

b) Checkout

Your backend calls the Create or Get Payment Address endpoint:

  • POST https://www.blockonomics.co/api/new_address
  • Required parameter: match — a string used to match part of your callback URL to identify the correct wallet (partial matches are supported).
  • Optional: crypto (BTC or USDT, defaults to BTC), reset (0 or 1).

Key behavior:

  • For BTC: reset=0 (default) creates a new address by advancing the index. reset=1 reuses the most recent address.
  • For USDT: The same fixed address is always returned.

Addresses do not expire — only the price quote has a time limit.

c) Monitor (WebSocket) & Callback

Use the WebSocket channel wss://www.blockonomics.co/payment/<address> to detect incoming payments in real-time. You can show confirmation to the customer as soon as an unconfirmed payment is seen — don’t rely on the customer staying on the page.

Blockonomics will post a callback to your server. The callback includes:

  • status (0 = unconfirmed, 2 = confirmed)
  • address
  • value / amount (in satoshis)
  • txid
  • Other fields (e.g., RBF flag if applicable)

Callbacks are automatically retried with exponential backoff. You can secure your callback URL by adding a secret parameter.

Core flow: Setup → Generate address + price → Watch via WebSocket → Receive callback → Deliver.

Quick Integration Paths: Native vs Payment Button / Checkout Widget

Native Payments API — Full control Build your own checkout UI and manage complete order logic. Ideal for deep customization. Documentation: Receiving Payments

Payment Button / Checkout Widget — Minimal coding A lite version using Blockonomics’ hosted payment button/widget.

  • Set up a parent product.
  • Create temporary products via API (valid for 7 days).
  • Embed their script.

Blockonomics handles the UI, emails, and customer-facing experience. You still process callbacks on your end. Documentation: Checkouts

Pro tip: Start with the Payment Button / Checkout Widget for faster implementation, then switch to Native if you need more control.

Testing — without risking real BTC

Blockonomics provides a Test Bench where you can fully simulate payment flows.

You can:

  • Generate new addresses
  • Trigger test unconfirmed (status 0), partially confirmed (status 1), and fully confirmed (status 2) states
  • Test your webhook and WebSocket handlers
  • Debug safely before going live

Security Best Practices

  • Only deliver goods/services after one or two blockchain confirmations. Zero-conf payments can be reversed (especially with RBF).
  • Use a secret parameter in your callback URL for added authentication.
  • Store order metadata in your database and link each order to its specific payment address.

Authentication

All API requests require an API Key in the request headers.

Quick Launch Plan

  1. Sign up, get your API key, add wallet + store with callback URL.
  2. Choose your path: Checkout Widget for speed or Native API for control.
  3. Implement backend:
  • Call new_address
  • Display Bitcoin address + QR to the customer
  • Connect WebSocket for real-time updates
  • Handle callbacks to update order status
  1. Test thoroughly using the Test Bench.
  2. Go live and monitor.

Final Thoughts

Blockonomics offers a smooth, flexible, and developer-friendly solution for Bitcoin payments — whether you prefer fast integration via widgets or full custom control via the native API. It stays pragmatic, secure, and truly non-custodial.

Read next

Comments ()