IOstamp API Documentation

# Set your API key as environment variable
export IOSTAMP_API_KEY="your-api-key-here"

curl -X POST https://api.iostamp.com/store-file-hash \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $IOSTAMP_API_KEY" \
  -d '{"fileData": "My important document data"}'

Base URL

Authentication

Protected endpoints require an API key sent in the request header.

⚠️ Security Best Practice: Never hardcode your API key in source code. Store it in an environment variable.

Step 1: Create a .env file:

IOSTAMP_API_KEY=your-api-key-here

Step 2: Include the key in the X-API-Key header.

Store Data Hash — POST /store-file-hash

Store a SHA256 hash of your data permanently on the Bitcoin SV blockchain.

Headers

Body

Example (Python)

import os
import requests
from dotenv import load_dotenv

load_dotenv()

response = requests.post(
    'https://api.iostamp.com/store-file-hash',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.getenv('IOSTAMP_API_KEY')
    },
    json={'fileData': 'My important document data'}
)
print(response.json())

Success Response

{
  "message": "Transaction broadcasted successfully!",
  "txid": "d77fdf46a060901c...",
  "fileHash": "3d298c392052bd7f...",
  "explorer": "https://whatsonchain.com/tx/..."
}

Store Raw Data (B://) — POST /store-data-onchain

Store full payloads formatting conforming to the B:// protocol so it is easily accessible by smart contracts and off-chain indexers.

Body

Success Response

{
  "message": "Data stored on-chain successfully!",
  "txid": "d7...",
  "dataSize": 1024,
  "mimeType": "application/json",
  "protocol": "B://",
  "explorer": "https://whatsonchain.com/tx/d7..."
}

Batch Merkle Stamping — POST /store-merkle-batch

Batch 1-10 items into a single transaction utilizing a Merkle tree root hash for high-volume efficiency.

Body

Success Response

{
  "message": "Merkle batch stamped on-chain successfully!",
  "txid": "d7...",
  "merkleRoot": "cf84...",
  "merkleReceipts": [ ... ]
}

Verify Transaction — GET /verify/{txid}

Retrieve the stored hash and transaction details from the blockchain.

curl https://api.iostamp.com/verify/d77fdf46a060901c...

Response Fields

Verify Data Match — POST /verify/{txid}/data

Compare your original data against the hash stored on the blockchain.

Request Body

Response

Official Node.js SDK

A robust SDK mapped to all IOStamp APIs.

npm install @iostamp/sdk

Usage

import { IOStamp } from '@iostamp/sdk';

const client = new IOStamp({ apiKey: process.env.IOSTAMP_API_KEY });
const receipt = await client.stamp({ data: 'Hello World' });
console.log('Stamped Tx:', receipt.txHash);

Smart Contract Builder

The IOStamp dashboard features an integrated full-feature Smart Contract Builder using sCrypt (TypeScript).

Developers can write, compile, and seamlessly prepare TypeScript-based BSV smart contracts utilizing the data structures stored via the IOstamp API to automate industrial settlements on-chain.

Health Check — GET /health

curl https://api.iostamp.com/health

Response

{
  "status": "running",
  "version": "2.0.0",
  "uptime": { "seconds": 86400, "formatted": "1d 0h 0m" },
  "endpoints": { "store": "POST /store-file-hash", ... },
  "rateLimit": { "store": "10 requests/minute", "global": "100 requests/15 minutes" }
}

Rate Limits