Bitwage API Documentation & Integration Guide
Comprehensive technical documentation for integrating Bitwage API with existing payroll systems, HR platforms, and custom applications for cryptocurrency salary management.
Getting Started with Bitwage API Integration
Essential information for developers beginning Bitwage API integration, including authentication, rate limits, and basic configuration.
API Overview and Capabilities
The Bitwage API provides programmatic access to cryptocurrency payroll functionality, enabling developers to integrate crypto salary conversion capabilities into existing systems. The API supports REST architecture with JSON payloads and standard HTTP status codes for response handling.
Our community analysis indicates the API supports both individual user operations and enterprise-level batch processing, with different endpoint access levels based on service tier subscriptions. The API is designed to handle high-frequency operations while maintaining security and compliance with financial services regulations.
Core API Capabilities
Payment Processing
Create, modify, and track cryptocurrency salary payments with real-time status updates and conversion tracking.
Account Management
Manage user accounts, allocation preferences, and security settings programmatically.
Reporting and Analytics
Access transaction history, tax documentation, and compliance reports through API endpoints.
Webhook Integration
Receive real-time notifications for payment status changes, compliance alerts, and system updates.
Authentication and Security
The Bitwage API uses API key authentication with optional OAuth 2.0 support for more complex integrations. All API requests must be made over HTTPS and include proper authentication headers for security and compliance.
API Key Authentication
Primary authentication method for server-to-server integrations using API keys with configurable permissions and scope limitations.
Request Headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-API-Version: v1API Key Management
- Keys can be generated through the dashboard settings
- Different permission levels available (read-only, write, admin)
- Key rotation supported for security best practices
- IP address restrictions can be configured
- Audit logging for all API key usage
OAuth 2.0 Authentication
Advanced authentication for applications requiring user consent and fine-grained permissions management.
Authorization Flow
# Authorization URL
https://api.bitwage.com/oauth/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&scope=payments:read,accounts:write
&redirect_uri=YOUR_CALLBACK_URL
# Token Exchange
POST /oauth/token
{
"grant_type": "authorization_code",
"code": "AUTHORIZATION_CODE",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}Security Best Practices
API Key Security
- Store API keys securely, never in client-side code
- Use environment variables for key storage
- Implement key rotation procedures
- Monitor API key usage patterns
Request Security
- Always use HTTPS for API requests
- Validate SSL certificates
- Implement request signing for sensitive operations
- Use idempotency keys for payment operations
Data Protection
- Encrypt sensitive data in transit and at rest
- Implement proper access controls
- Log security events and monitor for anomalies
- Follow PCI DSS guidelines for financial data
Rate Limits and Usage Guidelines
The Bitwage API implements rate limiting to ensure fair usage and system stability. Rate limits vary by endpoint type and subscription tier, with higher limits available for enterprise customers.
| Endpoint Category | Freelancer | Business | Enterprise | Time Window |
|---|---|---|---|---|
| Account Information | 100 requests | 500 requests | 2,000 requests | Per hour |
| Payment Operations | 50 requests | 200 requests | 1,000 requests | Per hour |
| Reporting Endpoints | 20 requests | 100 requests | 500 requests | Per hour |
| Webhook Configuration | 10 requests | 50 requests | 200 requests | Per day |
Rate Limit Response Handling
When rate limits are exceeded, the API returns HTTP 429 status with retry information in response headers.
Rate Limit Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 3600
HTTP/1.1 429 Too Many Requests
{
"error": "rate_limit_exceeded",
"message": "API rate limit exceeded",
"retry_after": 3600
}API Endpoint Reference
Comprehensive reference for all Bitwage API endpoints with request/response examples and parameter documentation.
Account Management Endpoints
Retrieves comprehensive account information including balance, preferences, and configuration settings.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| include_balances | boolean | No | Include cryptocurrency balances in response |
| include_preferences | boolean | No | Include allocation preferences |
Updates account preferences including cryptocurrency allocation percentages and notification settings.
Request Body Example
{
"allocations": {
"btc": 40.0,
"eth": 35.0,
"usdc": 25.0
},
"auto_convert": true,
"notification_preferences": {
"email_notifications": true,
"webhook_notifications": true,
"sms_notifications": false
}
}Payment Processing Endpoints
Creates a new cryptocurrency salary payment with specified allocation and conversion preferences.
Request Body
{
"amount": {
"value": "5000.00",
"currency": "USD"
},
"recipient": {
"email": "[email protected]",
"employee_id": "EMP-12345"
},
"allocations": {
"btc": 50.0,
"eth": 30.0,
"usdc": 20.0
},
"scheduled_date": "2024-02-01T00:00:00Z",
"idempotency_key": "unique_payment_identifier",
"metadata": {
"payroll_period": "2024-01",
"department": "engineering"
}
}Response
{
"id": "pay_1234567890",
"status": "pending",
"amount": {
"value": "5000.00",
"currency": "USD"
},
"conversions": [
{
"from_currency": "USD",
"to_currency": "BTC",
"amount": "2500.00",
"rate": "45000.00",
"converted_amount": "0.05555556"
}
],
"created_at": "2024-01-15T10:30:00Z",
"estimated_completion": "2024-01-15T11:00:00Z"
}Retrieves detailed information about a specific payment including status, conversions, and transaction hashes.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| payment_id | string | Unique payment identifier |
Processes multiple payments simultaneously with optimized network fee management and batch processing efficiencies.
Batch Request Example
{
"batch_id": "batch_2024_01_payroll",
"payments": [
{
"employee_id": "EMP-001",
"amount": "5000.00",
"allocations": { "btc": 60, "usdc": 40 }
},
{
"employee_id": "EMP-002",
"amount": "4500.00",
"allocations": { "eth": 70, "usdc": 30 }
}
],
"schedule_date": "2024-02-01T09:00:00Z",
"optimize_fees": true
}Reporting and Analytics Endpoints
Retrieves paginated transaction history with filtering and search capabilities for accounting and compliance purposes.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| start_date | string | 30 days ago | Start date for transaction search (ISO 8601) |
| end_date | string | current date | End date for transaction search (ISO 8601) |
| currency | string | all | Filter by cryptocurrency (btc, eth, usdc, etc.) |
| status | string | all | Filter by status (pending, completed, failed) |
| limit | integer | 50 | Number of transactions per page (max 200) |
| offset | integer | 0 | Number of transactions to skip |
Generates comprehensive tax documentation including cost basis calculations, gain/loss reports, and jurisdiction-specific forms.
Request Example
curl -X GET "https://api.bitwage.com/api/v1/reports/tax-documents?year=2023&format=pdf&jurisdiction=US" \
-H "Authorization: Bearer YOUR_API_KEY"Webhook Integration
Real-time event notifications through webhook endpoints for payment status updates, compliance alerts, and system notifications.
Webhook Configuration and Management
Bitwage webhooks provide real-time notifications for critical events, enabling your systems to respond immediately to payment status changes, compliance alerts, and other important updates. Webhooks are delivered as HTTP POST requests to URLs you configure.
Setting Up Webhooks
Create Webhook Endpoint
Configure an HTTPS endpoint in your application to receive webhook notifications.
POST /api/v1/webhooks
{
"url": "https://your-app.com/webhook/bitwage",
"events": [
"payment.completed",
"payment.failed",
"conversion.processed"
],
"secret": "webhook_secret_key"
}Verify Webhook Signatures
Implement signature verification to ensure webhooks are authentic and haven't been tampered with.
// Node.js example
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
return signature === expectedSignature;
}Handle Webhook Events
Process incoming webhooks and update your application state based on event types.
app.post('/webhook/bitwage', (req, res) => {
const event = req.body;
switch(event.type) {
case 'payment.completed':
handlePaymentCompleted(event.data);
break;
case 'payment.failed':
handlePaymentFailed(event.data);
break;
default:
console.log(`Unhandled event type: ${event.type}`);
}
res.status(200).send('OK');
});Available Webhook Events
Payment Events
payment.created
Triggered when a new payment is initiated
{
"id": "evt_123",
"type": "payment.created",
"created": 1640995200,
"data": {
"payment_id": "pay_456",
"amount": "5000.00",
"currency": "USD",
"recipient": "[email protected]"
}
}payment.completed
Triggered when payment processing is completed successfully
payment.failed
Triggered when payment processing fails with error details
Conversion Events
conversion.started
Triggered when cryptocurrency conversion begins
conversion.completed
Triggered when conversion completes with final rates and amounts
Compliance Events
compliance.alert
Triggered for compliance violations or warnings
account.suspended
Triggered when an account is suspended for compliance reasons
Webhook Best Practices
Idempotency
Handle duplicate webhook deliveries gracefully by implementing idempotency checks using event IDs.
Timeout Handling
Respond to webhooks within 10 seconds to avoid automatic retries and potential duplicate processing.
Error Handling
Implement proper error handling and logging for webhook processing failures and debugging.
Security
Always verify webhook signatures and use HTTPS endpoints to ensure data integrity and confidentiality.
SDK and Client Libraries
Official and community-maintained SDKs and client libraries for popular programming languages and frameworks.
Official SDK Support
JavaScript/TypeScript SDK
Comprehensive SDK for Node.js and browser applications with full TypeScript support and async/await patterns.
npm install @bitwage/sdk
import { BitwageClient } from '@bitwage/sdk';
const client = new BitwageClient({
apiKey: process.env.BITWAGE_API_KEY,
environment: 'production'
});
// Create a payment
const payment = await client.payments.create({
amount: { value: '5000.00', currency: 'USD' },
recipient: { email: '[email protected]' },
allocations: { btc: 60, usdc: 40 }
});
Python SDK
Python library with support for Django and Flask frameworks, including async support for high-performance applications.
pip install bitwage-python
from bitwage import BitwageClient
client = BitwageClient(api_key='your_api_key')
# Create a payment
payment = client.payments.create(
amount={'value': '5000.00', 'currency': 'USD'},
recipient={'email': '[email protected]'},
allocations={'btc': 60, 'usdc': 40}
)Community Libraries
Error Handling and Troubleshooting
Comprehensive guide to API error responses, common issues, and troubleshooting procedures for robust integration.
API Error Response Format
All API errors follow a consistent JSON format with detailed error information, error codes, and suggested resolution steps.
Standard Error Response
{
"error": {
"type": "invalid_request_error",
"code": "missing_parameter",
"message": "Missing required parameter: recipient.email",
"param": "recipient.email",
"request_id": "req_123456789",
"documentation_url": "https://docs.bitwage.com/api/errors#missing_parameter"
}
}HTTP Status Codes
| Status Code | Error Type | Description | Common Causes |
|---|---|---|---|
| 400 | Bad Request | Invalid request syntax or parameters | Missing required fields, invalid data format |
| 401 | Unauthorized | Authentication credentials missing or invalid | Invalid API key, expired token |
| 403 | Forbidden | Authenticated but lacking required permissions | Insufficient API key permissions, account restrictions |
| 404 | Not Found | Requested resource doesn't exist | Invalid endpoint, non-existent payment ID |
| 422 | Unprocessable Entity | Request format valid but contains semantic errors | Invalid allocation percentages, insufficient balance |
| 429 | Too Many Requests | Rate limit exceeded | Exceeding API call limits, need to implement backoff |
| 500 | Internal Server Error | Unexpected server error | Temporary service issues, maintenance periods |
Common Errors and Solutions
Insufficient Balance Error
{
"error": {
"type": "payment_error",
"code": "insufficient_balance",
"message": "Insufficient USD balance for conversion. Required: $5000.00, Available: $2500.00",
"details": {
"required_amount": "5000.00",
"available_balance": "2500.00",
"currency": "USD"
}
}
}Solution:
- Check account balance before initiating payments
- Implement balance validation in your application
- Set up low balance alerts and notifications
- Consider implementing automatic top-up mechanisms
Invalid Allocation Error
{
"error": {
"type": "validation_error",
"code": "invalid_allocation",
"message": "Allocation percentages must sum to 100. Current total: 85%",
"details": {
"provided_allocations": {
"btc": 50,
"eth": 35
},
"total_percentage": 85
}
}
}Solution:
- Ensure allocation percentages sum exactly to 100%
- Validate allocations client-side before API calls
- Implement allocation normalization functions
- Provide clear user feedback for allocation errors
Retry Logic and Best Practices
Implement robust retry logic for handling transient errors and ensuring reliable payment processing.
Exponential Backoff Implementation
async function apiCallWithRetry(apiCall, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await apiCall();
} catch (error) {
if (attempt === maxRetries || !isRetryableError(error)) {
throw error;
}
const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms`);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
function isRetryableError(error) {
const retryableCodes = [429, 500, 502, 503, 504];
return retryableCodes.includes(error.status);
}Retry Guidelines
Retryable Errors
- Network timeouts
- Rate limiting (429)
- Server errors (5xx)
- Temporary service unavailability
Non-Retryable Errors
- Authentication errors (401)
- Permission errors (403)
- Validation errors (400, 422)
- Resource not found (404)
Retry Strategy
- Maximum 3-5 retry attempts
- Exponential backoff with jitter
- Maximum delay of 30 seconds
- Circuit breaker for system failures