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
Real-time notifications
https://api.verifybtc.com/v1All API requests should be made to this base URL. HTTPS is required for all requests.
The VerifyBTC API uses API keys to authenticate requests. Include your API key in the X-API-Key header.
Example Request
curl -X GET https://api.verifybtc.com/v1/verifications \
-H "X-API-Key: your_api_key_here"Getting an API Key: Log in to your dashboard and navigate to the API Keys page to create a new API key.
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: 1640995200When rate limit is exceeded, the API returns a 429 Too Many Requests status code.
POST /api/verificationsCreates 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.verifybtc.com/v1/api/verifications \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"bitcoin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"amount": 100000,
"broker_context": "Order #12345"
}'GET /api/verifications?page=1&limit=20&status=pendingRetrieves 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 /api/verifications/:idRetrieves 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"
}POST /api/verifications/:id/cancelCancels a pending verification.
Request Body (optional)
{
"reason": "Customer requested cancellation"
}Response (200 OK)
{
"message": "Verification cancelled successfully",
"success": true,
"verification": { ... }
}GET /api/verifications/:id/reportRetrieves a downloadable PDF report for a verified signature.
Response (200 OK)
{
"report_url": "https://cdn.verifybtc.com/reports/ver_123...",
"verification_hash": "sha256:abc123..."
}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
Bad Request - Invalid parameters
Unauthorized - Invalid API key
Not Found - Resource doesn't exist
Too Many Requests - Rate limit exceeded
Internal Server Error - Server error
If you have questions or need assistance integrating the VerifyBTC API, please contact our support team or check out additional resources: