API Documentation

Transaction Monitor API

A lightweight, queue-based service for monitoring transaction statuses on the Stacks blockchain. Real-time status checks with automatic fallback to background monitoring.

GitHub

Quick Start

Get started with the Transaction Monitor API in seconds

1. Add transactions to the monitoring queue

curl -X POST https://tx-monitor.charisma.ai/api/v1/queue/add \
  -H "Content-Type: application/json" \
  -d '{"txids": ["0x123abc..."]}'

2. Check transaction status in real-time

curl https://tx-monitor.charisma.ai/api/v1/status/0x123abc...

3. Monitor queue statistics

curl https://tx-monitor.charisma.ai/api/v1/queue/stats

API Endpoints

All endpoints are available under the /api/v1 namespace

Queue Management

POST/api/v1/queue/add

Add one or more transaction IDs to the monitoring queue

Request Body:

{
  "txids": ["0x123abc...", "0x456def..."]
}
GET/api/v1/queue/stats

Get queue statistics and health metrics

Response:

{
  "queueSize": 15,
  "processingHealth": "healthy",
  "totalProcessed": 247,
  "totalSuccessful": 232,
  "totalFailed": 15
}

Transaction Status

GET/api/v1/status/{txid}

Get real-time transaction status. Waits up to 30 seconds for confirmation if not cached. Returns 404 if transaction not found after timeout (likely never broadcasted).

Response:

{
  "txid": "0x123abc...",
  "status": "success",
  "blockHeight": 142847,
  "blockTime": 1703123456,
  "fromCache": false,
  "checkedAt": 1703123500000
}

Cache Headers:

Cache-Control: public, max-age=3600, stale-while-revalidate=86400
ETag: "success-1703123500000"
X-Cache-Status: HIT

Error Response (404):

{
  "success": false,
  "error": "Transaction not found",
  "message": "Transaction ID not found on blockchain"
}

Caching Strategy

Intelligent HTTP caching to optimize performance and reduce blockchain API calls

Confirmed Transactions

Immutable data cached for maximum efficiency

Cache TTL:1 hour
Stale while revalidate:24 hours
ETag support:Yes

Pending Transactions

Frequently changing data with short cache times

Cache TTL:30 seconds
Stale while revalidate:5 minutes
Must revalidate:Yes

Transaction Statuses

Understanding the different transaction states

success

Transaction successfully confirmed on the blockchain

abort_by_response

Transaction failed due to contract execution error

abort_by_post_condition

Transaction failed due to post-condition check failure

pending

Transaction is still being processed by the network

not_found

Transaction not found after 30 seconds - likely never broadcasted

Key Features

Why choose Transaction Monitor for your blockchain monitoring needs

Real-time Monitoring

Get instant status updates with 30-second real-time checks. Automatic fallback to background monitoring for pending transactions.

Queue-based Processing

Efficient queue management with automatic cleanup. Handles thousands of transactions with minimal resource usage.

Smart Caching

Intelligent HTTP caching based on transaction status. Confirmed transactions cached for 1 hour, pending for 30 seconds.

Integration Examples

Common patterns for integrating with the Transaction Monitor API

JavaScript/TypeScript

async function monitorTransaction(txid: string) {
  // Add to queue for monitoring
  await fetch('/api/v1/queue/add', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ txids: [txid] })
  });

  // Check status immediately
  const response = await fetch(`/api/v1/status/${txid}`);
  const { data } = await response.json();
  
  return data.status; // 'success', 'pending', etc.
}

Python

import requests

def monitor_transaction(txid):
    # Add to queue
    requests.post('/api/v1/queue/add', 
                  json={'txids': [txid]})
    
    # Check status
    response = requests.get(f'/api/v1/status/{txid}')
    return response.json()['data']['status']

API Tester

Test the API endpoints directly from the documentation

GET/api/v1/queue/stats
Get queue statistics and health metrics
GET/api/v1/status/{txid}
Get real-time transaction status
POST/api/v1/queue/add
Add transactions to the monitoring queue

Testing Note

These are live API calls to the transaction monitor service. The endpoints will return real data from the monitoring queue. Use placeholder transaction IDs for testing the POST endpoint.

Status endpoint: Shows a 30-second countdown during real-time checking. If a transaction isn't found after 30 seconds, it returns 404 (likely never broadcasted).
Caching: fromCache indicates our KV store cache. Browser may also cache HTTP responses (shown in dev tools).