JungleBus

Real-time BSV blockchain data streaming from GorillaPool. Indexes all Bitcoin transactions with special handling for data protocols.

When to Use

• Subscribe to transactions matching specific patterns
• Stream real-time mempool and block data
• Build indexers or notification systems
• Monitor addresses or script patterns
• Track 1Sat Ordinals, MAP, BAP, and other protocols

Creating a Subscription

Step-by-Step (Dashboard)

1. Visit https://junglebus.gorillapool.io
2. Sign in or create an account
3. Navigate: Dashboard > Subscriptions > Create New
4. Fill in subscription details:
   • ID: Auto-generated unique identifier
   • Name: Descriptive name for your subscription
   • Description: What this subscription monitors

Subscription Filters

Define what transactions to capture using AND logic (all conditions must match):

Filter	Description	Examples
Addresses	Comma-separated Bitcoin addresses	1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Input types	Input script types	ordlock, sigil
Output types	Output classifications	aip, bap, bitcom, map, ord, run, token_stas, pubkeyhash, nulldata
Contexts	Main data from OP_RETURN outputs	Protocol-specific identifiers
Sub contexts	Secondary data from outputs	Depends on output type
Data keys	Key=value pairs from transactions	app=junglebus, type=post

Note: Multiple values in a single field use AND logic - all must be present in the transaction.

Common Subscription Patterns

Monitor 1Sat Ordinals:

• Output types: ord
• Contexts: image/png, text/plain (content types)

Monitor BAP Identity:

• Output types: bap
• Contexts: 1BAPSuaPnfGnSBM3GLV9yhxUdYe4vGbdMT (BAP address)

Monitor MAP Protocol:

• Output types: map
• Contexts: 1PuQa7K62MiKCtssSLKy1kh56WWU7MtUR5 (MAP prefix)

Monitor Specific Address:

• Addresses: 1YourAddressHere

JavaScript Client

Installation

bun add @gorillapool/js-junglebus

Basic Usage

import { JungleBusClient, ControlMessageStatusCode } from '@gorillapool/js-junglebus';

const client = new JungleBusClient("junglebus.gorillapool.io", {
  useSSL: true,
  onConnected(ctx) { 
    console.log("Connected", ctx); 
  },
  onConnecting(ctx) { 
    console.log("Connecting", ctx); 
  },
  onDisconnected(ctx) { 
    console.log("Disconnected", ctx); 
  },
  onError(ctx) { 
    console.error("Error", ctx); 
  }
});

// Subscribe to a subscription ID
const subscriptionId = "your-subscription-id";
const fromBlock = 750000;

client.Subscribe(
  subscriptionId,
  fromBlock,
  (tx) => {
    // Confirmed transaction received
    console.log("TX:", tx.id, "at height", tx.block_height);
    console.log("Output types:", tx.output_types);
    console.log("Contexts:", tx.contexts);
  },
  (status) => {
    // Status updates
    if (status.statusCode === ControlMessageStatusCode.BLOCK_DONE) {
      console.log("Block done:", status.block);
    } else if (status.statusCode === ControlMessageStatusCode.WAITING) {
      console.log("Waiting for new block...");
    } else if (status.statusCode === ControlMessageStatusCode.REORG) {
      console.log("Reorg triggered:", status);
    }
  },
  (error) => {
    // Subscription errors
    console.error("Subscription error:", error);
  },
  (mempoolTx) => {
    // Unconfirmed mempool transaction
    console.log("Mempool TX:", mempoolTx.id);
  }
);

Lite Mode (Lower Bandwidth)

// Last parameter = true for lite mode
client.Subscribe(
  subscriptionId, 
  fromBlock, 
  onTx, 
  onStatus, 
  onError, 
  onMempool, 
  true // Lite mode - only txid and block height
);

Transaction Data Format

Full Transaction Object

{
  "id": "e597af34eb78b599b7d458110a3cc602a40dedd020db684992b40926217612a4",
  "block_hash": "000000000000000006296f1e5437dd6c01b9b5471691a89a9c7d8e9f06920da5",
  "block_height": 750000,
  "block_time": 1658878267,
  "block_index": 3,
  "transaction": "0100000002...",
  "merkle_proof": "AAOkEnYhJgm0kklo2yDQ7Q2kAsY8ChFY1LeZtXjrNK+X...",
  "addresses": [
    "18FJd9tDLAC2S6PCzfnqNfUMXhZuPfsFUm",
    "1P7UWRLdL5pH2Si1GauwASYAA1LQHs2z45"
  ],
  "inputs": [],
  "outputs": [
    "76a9144f7d6a485e09770f947c0ba38d15050a5a80b6fa88ac",
    "76a914f28c3992dd6a43eccaed16f3f7fb6ac8da1bc3c288ac"
  ],
  "input_types": [],
  "output_types": ["nulldata", "pubkeyhash", "run"],
  "contexts": [
    "555aad1953bcfef8c7779d246fa03efae0412ed700b955435831814f5be3a82b_o1",
    "c2c4c971e85b499c29a8ab2148fd324fe12b550b8f4f57658a4686e011d8fd58_o1"
  ],
  "sub_contexts": [
    "2e729d39a9cd300f5100044a54204e6d8b43fe49555309361fdc3d8565323499"
  ],
  "data": []
}

Field Descriptions

Field	Type	Description
id	string	Transaction ID (txid)
block_hash	string	Block hash where transaction was mined
block_height	number	Block height
block_time	number	Unix timestamp
block_index	number	Position of transaction in block
transaction	string	Full transaction in hex
merkle_proof	string	TSC-compatible binary merkle proof
addresses	string[]	All addresses found in transaction
outputs	string[]	Output scripts (capped to 1024 chars)
output_types	string[]	Classifications (aip, bap, map, ord, etc.)
contexts	string[]	Main data from OP_RETURN outputs
sub_contexts	string[]	Secondary data from outputs
data	string[]	Other key=value attributes

Supported Protocols

JungleBus automatically recognizes and indexes these protocols:

Protocol	Output Type	Context	Description
1Sat Outputs	1sat	none	1 satoshi outputs
1Sat Ordinals	ord	content-type	Inscriptions with content type
AIP	aip	protocol data	Bitcoin Attestation Protocol
B Protocol	b	protocol data	B:// file storage
BAP	bap	1BAPSuaPnfGnSBM3GLV9yhxUdYe4vGbdMT	BAP identity
Bitcom	bitcom	protocol data	Bitcom protocol
Boost	boost	protocol data	Boost POW
MAP	map	1PuQa7K62MiKCtssSLKy1kh56WWU7MtUR5	MAP protocol
Run	run	protocol data	Run tokens
STAS	token_stas	protocol data	STAS tokens

REST API Endpoints

Get Transaction

curl https://junglebus.gorillapool.io/v1/transaction/get/{txid}

Returns full transaction with parsed data.

Get Address History

curl https://junglebus.gorillapool.io/v1/address/get/{address}

Returns:

[
  {
    "id": "8859250950ecbb7025731c1206e277e344a6db5f285274b7a1d2817980ab8e64",
    "address": "13qRymPwRxAr7oRdAoFdo5Wp8815sstHE5",
    "transaction_id": "eb197a43a7c4ed230a7125d7e7bf5990cd60be8ff0f59b8fffdfd91d52dfce82",
    "block_hash": "0000000000000000002be95240df5e4215e6878259dce8b9df08650641fdd40a",
    "block_index": 50545
  }
]

Get Block Header

curl https://junglebus.gorillapool.io/v1/block_header/get/{block_hash}

Returns:

{
  "hash": "000000000000000006296f1e5437dd6c01b9b5471691a89a9c7d8e9f06920da5",
  "coin": 1,
  "height": 750000,
  "time": 1658878267,
  "nonce": 4188280238,
  "version": 671080448,
  "merkleroot": "e88b40ac9367eb11dd918416b668e67f09bf24550eac93de7f2d68a0ca0c6eae",
  "bits": "180f4e90",
  "synced": 8971
}

Control Message Status Codes

import { ControlMessageStatusCode } from '@gorillapool/js-junglebus';

// Available codes:
ControlMessageStatusCode.BLOCK_DONE    // Block processing complete
ControlMessageStatusCode.WAITING       // Waiting for new block
ControlMessageStatusCode.REORG         // Blockchain reorganization
ControlMessageStatusCode.ERROR         // Error occurred

Go Client

go get github.com/GorillaPool/go-junglebus

package main

import (
    "github.com/GorillaPool/go-junglebus"
)

func main() {
    client, _ := junglebus.New(
        junglebus.WithHTTP("https://junglebus.gorillapool.io"),
    )

    client.Subscribe("subscription-id", 750000, func(tx *junglebus.Transaction) {
        fmt.Printf("TX: %s at height %d\n", tx.Id, tx.BlockHeight)
        fmt.Printf("Types: %v\n", tx.OutputTypes)
    })
}

JungleBus vs WhatsOnChain

Feature	JungleBus	WhatsOnChain
Real-time streaming	✅ Yes	❌ No
Transaction history	✅ Yes	✅ Yes
Address balance	❌ No	✅ Yes
UTXOs	❌ No	✅ Yes
Price data	❌ No	✅ Yes
Parsed tx data	✅ Yes	⚠️ Limited
Protocol indexing	✅ Yes	❌ No

Use JungleBus for: Streaming, protocol monitoring, real-time indexing Use WhatsOnChain for: Balances, UTXOs, price data

Dashboard Workflow

junglebus.gorillapool.io
    ↓
Dashboard → Subscriptions → Create New
    ↓
Configure filters:
  - Addresses (optional)
  - Input types (optional)
  - Output types (required for protocol filtering)
  - Contexts (required for specific protocols)
  - Sub contexts (optional)
  - Data keys (optional)
    ↓
Save subscription
    ↓
Copy subscription ID
    ↓
Use in your code

Links

• Dashboard: https://junglebus.gorillapool.io
• Documentation: https://junglebus.gorillapool.io/docs
• JavaScript Client: https://www.npmjs.com/package/@gorillapool/js-junglebus
• Go Client: https://github.com/GorillaPool/go-junglebus
• GitHub: https://github.com/GorillaPool/js-junglebus