Bitcoin Cash Hackathon 2025

API
Documentation

Developer-Friendly REST API

Integrate BCH address conversion into your application with our fast, reliable, and free RESTful API

<100ms
Response Time
100%
Accuracy
3
Format Types
Free
Open Source

Base URL

https://bch-address-harmony.vercel.app

Replace with your deployed domain. All endpoints are relative to this base URL.

🔓 Authentication

No authentication required! Our API is completely open and free to use. Rate limiting may apply for excessive usage.

POST

/api/convert

Convert a single BCH address between Legacy and CashAddr formats.

Request

Body Parameters

ParameterTypeRequiredDescription
addressstringYesBCH address in any format (Legacy or CashAddr)

Example Request (cURL)

curl -X POST https://bch-address-harmony.vercel.app/api/convert \
  -H "Content-Type: application/json" \
  -d '{"address": "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu"}'

Example Request (JavaScript)

const response = await fetch('/api/convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    address: '1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu'
  })
});
const data = await response.json();
console.log(data);

Response

{
  "original": "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu",
  "originalType": "Legacy Format",
  "legacy": "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu",
  "cashAddrWithPrefix": "bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a",
  "cashAddrNoPrefix": "qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a",
  "addressType": "P2PKH",
  "success": true
}

Error Response

{
  "success": false,
  "error": "Invalid BCH address format"
}
POST

/api/batch

Convert multiple BCH addresses in a single request (up to 10,000 addresses).

Request

Body Parameters

ParameterTypeRequiredDescription
addressesstring[]YesArray of BCH addresses (max 10,000)

Example Request (cURL)

curl -X POST https://bch-address-harmony.vercel.app/api/batch \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu",
      "bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a",
      "3J98t1WpEZ73CNmYviecrnyiWrnqRhWNLy"
    ]
  }'

Example Request (JavaScript)

const addresses = [
  '1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu',
  'bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a',
  '3J98t1WpEZ73CNmYviecrnyiWrnqRhWNLy'
];

const response = await fetch('/api/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ addresses })
});

const data = await response.json();
console.log(`Converted ${data.successful}/${data.total} addresses`);

Response

{
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "index": 1,
      "input": "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu",
      "legacy": "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu",
      "cashAddrWithPrefix": "bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a",
      "cashAddrNoPrefix": "qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a",
      "addressType": "P2PKH",
      "success": true
    }
  ]
}

Response Fields Reference

FieldTypeDescription
legacystringLegacy format address (1xxx or 3xxx)
cashAddrWithPrefixstringCashAddr with bitcoincash: prefix (recommended)
cashAddrNoPrefixstringCashAddr without prefix
addressTypestringEither "P2PKH" or "P2SH"
originalstringOriginal input address
originalTypestring"Legacy Format" or "CashAddr Format"

HTTP Status Codes

CodeDescription
200Success - Address converted successfully
400Bad Request - Invalid address format or missing parameters
429Too Many Requests - Rate limit exceeded
413Payload Too Large - Request body exceeds size limit
500Internal Server Error - Something went wrong on our end

⚡ Rate Limits & Security

  • • Single Convert: 100 requests per minute per IP address
  • • Batch Convert: 20 requests per minute per IP address
  • • Request Size: Max 1MB for single, 10MB for batch
  • • Batch Size: Max 10,000 addresses per request
  • • Rate Limit Headers: Check X-RateLimit-* headers in responses
  • • 429 Status: Rate limit exceeded - includes Retry-After header

Note: Rate limits are enforced per IP address. For higher limits, consider using the web interface or implementing client-side caching.

Language-Specific Examples

Python

import requests

url = "https://bch-address-harmony.vercel.app/api/convert"
payload = {"address": "1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu"}
response = requests.post(url, json=payload)
data = response.json()

if data.get("success"):
    print(f"Legacy: {data['legacy']}")
    print(f"CashAddr: {data['cashAddrWithPrefix']}")
else:
    print(f"Error: {data.get('error')}")

Node.js

const axios = require('axios');

const convertAddress = async (address) => {
  try {
    const response = await axios.post(
      'https://bch-address-harmony.vercel.app/api/convert',
      { address }
    );
    
    return response.data;
  } catch (error) {
    console.error('Conversion failed:', error.response?.data?.error);
    throw error;
  }
};

// Usage
convertAddress('1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu')
  .then(result => console.log(result))
  .catch(err => console.error(err));

PHP

<?php
$url = 'https://bch-address-harmony.vercel.app/api/convert';
$data = array('address' => '1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu');
$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

if ($response['success']) {
    echo "Legacy: " . $response['legacy'] . "\n";
    echo "CashAddr: " . $response['cashAddrWithPrefix'] . "\n";
}
?>

💡 Use Cases

🏦 Wallet Applications

Convert addresses for compatibility with different wallet formats

📊 Block Explorers

Display addresses in multiple formats for user convenience

💱 Exchange Platforms

Validate and normalize deposit addresses from users

🛠️ Developer Tools

Integrate address conversion into BCH development workflows

🤝 Support & Feedback

Have questions or feedback? We'd love to hear from you!

🐛 Report Issues: Open an issue on GitHub

💬 Community: Join BCH Telegram channel

📧 Contact: Built for BCH Blaze 2025 Hackathon

Back to Converter