API Reference

Webhooks

VerifyBTC API Documentation

A comprehensive guide to integrating Bitcoin signature verification into your applications using the VerifyBTC API.

Authentication

Get started with API keys

Rate Limits

Understand request limits

Security

Best practices & HTTPS

Webhooks →

Real-time notifications

Base URL

https://api.verifybitcoin.io

All API requests should be made to this base URL. HTTPS is required for all requests.

Authentication

The VerifyBTC API uses API keys to authenticate requests. Include your API key in the X-API-Key header with every request.

Getting an API Key

1. Log in to your Dashboard

2. Go to Settings → API Keys

3. Click "Create New API Key"

4. Copy and store your key securely (it won't be shown again)

cURL Example

curl -X POST https://api.verifybitcoin.io/api/verifications \ -H "X-API-Key: vbtc_live_abc123..." \ -H "Content-Type: application/json" \ -d '{"bitcoin_address": "bc1q...", "amount": 100000}'

Node.js Example

const response = await fetch('https://api.verifybitcoin.io/api/verifications', { method: 'POST', headers: { 'X-API-Key': process.env.VERIFYBTC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ bitcoin_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', amount: 100000, broker_context: 'Order #12345' }) }); const verification = await response.json(); console.log(verification.id, verification.public_link);

Python Example

import os import requests response = requests.post( 'https://api.verifybitcoin.io/api/verifications', headers={ 'X-API-Key': os.environ['VERIFYBTC_API_KEY'], 'Content-Type': 'application/json' }, json={ 'bitcoin_address': '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', 'amount': 100000, 'broker_context': 'Order #12345' } ) verification = response.json() print(verification['id'], verification['public_link'])

Security Best Practices: Never expose your API key in client-side code. Store it in environment variables and only use it from your server.

Rate Limits

API rate limits are configurable per API key. Default limits apply if not specified.

Response Headers

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 X-RateLimit-Reset: 1640995200

When rate limit is exceeded, the API returns a 429 Too Many Requests status code.

API Endpoints

Create Verification

POST
POST /api/verifications

Creates a new Bitcoin signature verification request.

Request Body

{ "bitcoin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "amount": 100000, "broker_context": "Order #12345" }

Response (201 Created)

{ "id": "ver_1234567890", "bitcoin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "challenge_message": "Verify ownership: abc123...", "amount": 100000, "status": "pending", "verification_token": "tok_abcdef123456", "public_link": "https://verify.btc/v/tok_abcdef123456", "broker_context": "Order #12345", "created_at": "2024-01-15T10:30:00Z", "expires_at": "2024-01-15T22:30:00Z" }

Example with cURL

curl -X POST https://api.verifybitcoin.io/api/verifications \ -H "X-API-Key: vbtc_live_abc123..." \ -H "Content-Type: application/json" \ -d '{ "bitcoin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "amount": 100000, "broker_context": "Order #12345" }'

List Verifications

GET
GET /api/verifications?page=1&limit=20&status=pending

Retrieves a paginated list of verifications with optional filtering.

Query Parameters

page

(optional) - Page number (default: 1)

limit

(optional) - Results per page (default: 20, max: 100)

status

(optional) - Filter by status (pending, verified, failed, expired, cancelled)

Response (200 OK)

{ "verifications": [ { "id": "ver_1234567890", "bitcoin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "status": "verified", "amount": 100000, "created_at": "2024-01-15T10:30:00Z", "verified_at": "2024-01-15T11:45:00Z" } ], "total": 42, "page": 1, "limit": 20, "has_more": true }

Get Verification

GET
GET /api/verifications/:id

Retrieves details of a specific verification.

Response (200 OK)

{ "id": "ver_1234567890", "bitcoin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "challenge_message": "Verify ownership: abc123...", "amount": 100000, "status": "verified", "signature": "H8k7...", "broker_context": "Order #12345", "created_at": "2024-01-15T10:30:00Z", "expires_at": "2024-01-15T22:30:00Z", "verified_at": "2024-01-15T11:45:00Z" }

Cancel Verification

POST
POST /api/verifications/:id/cancel

Cancels a pending verification.

Request Body (optional)

{ "reason": "Customer requested cancellation" }

Response (200 OK)

{ "message": "Verification cancelled successfully", "success": true, "verification": { ... } }

Get Verification Report

GET
GET /api/verifications/:id/report

Retrieves a downloadable PDF report for a verified signature.

Response (200 OK)

{ "report_url": "https://cdn.verifybitcoin.io/reports/ver_123...", "verification_hash": "sha256:abc123..." }

Error Responses

All errors return a JSON response with an error message and appropriate HTTP status code.

Error Response Format

{ "error": "Invalid API key", "code": "INVALID_API_KEY", "status": 401 }

Common Error Codes

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid API key

404

Not Found - Resource doesn't exist

429

Too Many Requests - Rate limit exceeded

500

Internal Server Error - Server error

OpenAPI Specification

Download the OpenAPI 3.0 specification to generate client SDKs in your preferred programming language, import into API testing tools like Postman, or integrate with other development workflows.

OpenAPI 3.0 JSON

Machine-readable API specification

Download Spec

Interactive Documentation

Explore the API interactively with Swagger UI:

https://api.verifybitcoin.io/api-docs

Ready to Get Started?

Start verifying Bitcoin ownership in minutes. Create a free account and get your API key — no credit card required.

Questions? Email us at support@verifybtc.com

Need Help?

If you have questions or need assistance integrating the VerifyBTC API, please contact our support team or check out additional resources:

Webhooks Documentation →

Go to Dashboard →