Lightning Nodes

Troubleshooting & Solutions

Practical solutions for common issues on Comet Platform. Organized by problem category for quick navigation.

Estimated reading time: 7 minutes

Note: Bitcoin Core nodes not currently available. References are for future use. Currently supported: LND Node and LITD (TAPD) Node.

Diagnostic Tools

Dashboard:

Node health indicators
Recent error logs
Performance metrics
Alert history

API Examples:

Get node details and status:

# curl
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" \
  -H "Content-Type: application/json"
# Or use API key:
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "X-API-Key: {API_KEY}" \
  -H "Content-Type: application/json"

// JavaScript/TypeScript (fetch API)
const response = await fetch(
  `https://provisioning.cometplatform.com/api/company/${COMPANY_ID}/nodes/${NODE_ID}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${AUTH_TOKEN}`, // or 'X-API-Key': API_KEY
      'Content-Type': 'application/json'
    }
  }
);
const nodeInfo = await response.json();
console.log('Node status:', nodeInfo.status);
console.log('API endpoint:', nodeInfo.api_endpoint);

# Python (requests library)
import requests

url = f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}"
headers = {
    "Authorization": f"Bearer {AUTH_TOKEN}",  # or "X-API-Key": API_KEY
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
node_info = response.json()
print(f"Node status: {node_info['status']}")
print(f"API endpoint: {node_info['api_endpoint']}")

Common Issues

Cannot Connect to Node API

Symptoms: Connection refused, timeouts, "Host unreachable"

Diagnostics:

# curl
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

// JavaScript
const response = await fetch(
  `https://provisioning.cometplatform.com/api/company/${COMPANY_ID}/nodes/${NODE_ID}`,
  {
    headers: { 'Authorization': `Bearer ${AUTH_TOKEN}` }
  }
);
const node = await response.json();
console.log('Status:', node.status);
console.log('Endpoint:', node.api_endpoint);

# Python
import requests
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
node = response.json()
print(f"Status: {node['status']}")
print(f"Endpoint: {node['api_endpoint']}")

Solutions:

Wrong Endpoint

Verify you're using the correct endpoint format from the node details:

# Get node details to verify endpoint
import requests
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
node = response.json()
print(f"API endpoint: {node['api_endpoint']}")

Firewall/Network

Check corporate firewall
Try different network
Verify ports 8080/10009 accessible

Intermittent Connection Drops

Symptoms: Connections work sometimes, "Connection reset by peer"

Diagnostics:

Check node status via API. Note: Detailed metrics and logs are available through the dashboard:

# curl - Check node status
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Python
import requests
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
node = response.json()
print(f"Status: {node['status']}")
print(f"Command history: {node.get('command_history', [])}")

Solutions:

Implement Retry Logic

# Python with exponential backoff
import requests
import time

def api_call_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, timeout=10)
            response.raise_for_status()
            return response.json()
        except (requests.exceptions.RequestException, requests.exceptions.Timeout) as e:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt
            print(f"Attempt {attempt + 1} failed, retrying in {wait_time}s...")
            time.sleep(wait_time)
    return None

# Usage
node_info = api_call_with_retry(
    f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
    headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)

// JavaScript with exponential backoff
async function apiCallWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, { ...options, signal: AbortSignal.timeout(10000) });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const waitTime = Math.pow(2, attempt) * 1000;
      console.log(`Attempt ${attempt + 1} failed, retrying in ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
  }
}

// Usage
const nodeInfo = await apiCallWithRetry(
  `https://provisioning.cometplatform.com/api/company/${COMPANY_ID}/nodes/${NODE_ID}`,
  { headers: { 'Authorization': `Bearer ${AUTH_TOKEN}` } }
);

Resource Exhaustion

Node resource metrics are available through the dashboard. To upgrade node tier, contact support or use the dashboard:

# Check node current tier
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '.tier'

# Python
import requests
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
node = response.json()
print(f"Current tier: {node['tier']}")
# To upgrade, contact support or use dashboard

Node Stuck Syncing

Symptoms: Sync progress not advancing, stuck on "Syncing"

Diagnostics:

# curl - Get node info
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

For LND nodes, check sync status and peers via node's native API:

# curl - Get LND info (replace {API_ENDPOINT} with node's api_endpoint)
curl -X GET "https://{API_ENDPOINT}/v1/getinfo" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Python - Get node info from provisioning API
import requests

# Get node details
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
node = response.json()
api_endpoint = node['api_endpoint']

# For LND nodes, check sync status
if node['type'] == 'LND':
    # Use node's native API endpoint
    lnd_response = requests.get(
      f"https://{api_endpoint}/v1/getinfo",
      headers={'Grpc-Metadata-macaroon': MACAROON_HEX}
    )
    lnd_info = lnd_response.json()
    print(f"Synced: {lnd_info.get('synced_to_chain', False)}")
    print(f"Block height: {lnd_info.get('block_height', 0)}")

Solutions:

Insufficient Peers (<5)

Node configuration changes require support assistance or dashboard access. Contact support for peer configuration changes.

Resource Constrained

Node tier upgrades can be done through the dashboard or by contacting support. Current tier can be checked via API:

# curl
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '.tier'

Restart Node

Stop and start the node:

# curl - Stop node
curl -X POST "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/stop" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Wait a moment, then start
curl -X POST "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/start" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Python
import requests
import time

base_url = f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}"
headers = {"Authorization": f"Bearer {AUTH_TOKEN}"}

# Stop node
requests.post(f"{base_url}/stop", headers=headers)
time.sleep(5)  # Wait before starting

# Start node
response = requests.post(f"{base_url}/start", headers=headers)
print(f"Node status: {response.json()['status']}")

Sync Repeatedly Resets

Symptoms: Progress resets to 0%, blocks re-downloaded

Diagnostics:

Check node status and command history for errors. Detailed logs are available through the dashboard:

# curl - Check node status and command history
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '.command_history'

Solutions:

Database Corruption

Database restoration and rebuild operations require support assistance. Contact support@cometcash.com with your node ID for assistance with database issues.

Insufficient Disk/Memory

Node tier upgrades (which include more storage) can be done through the dashboard or by contacting support. Check current tier via API:

# Python
import requests
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
node = response.json()
print(f"Current tier: {node['tier']}")
# Upgrade through dashboard or contact support

"Unauthorized" or "Invalid Macaroon"

Symptoms: 401 errors, "Invalid macaroon signature"

Diagnostics:

Download encrypted macaroon and test connection:

# curl - Download encrypted macaroon
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/macaroon/admin" \
  -H "Authorization: Bearer {AUTH_TOKEN}" \
  -o encrypted_macaroon.json

# Test LND connection (replace {API_ENDPOINT} with node's api_endpoint from node details)
curl -X GET "https://{API_ENDPOINT}/v1/getinfo" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Python - Download and decrypt macaroon
import requests
import json
from cryptography.fernet import Fernet
import hashlib
from base64 import b64encode

# Download encrypted macaroon
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/macaroon/admin",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
macaroon_data = response.json()

# Decrypt macaroon (example - use your decryption method)
# This is a simplified example - use proper decryption based on your encryption scheme
password = "YOUR_PASSWORD"
key = hashlib.pbkdf2_hmac('sha256', password.encode(), b'salt', 100000)
f = Fernet(b64encode(key))
decrypted_macaroon = f.decrypt(macaroon_data['macaroon'].encode())

# Test LND connection
lnd_response = requests.get(
  f"https://{API_ENDPOINT}/v1/getinfo",
  headers={'Grpc-Metadata-macaroon': decrypted_macaroon.hex()}
)
print(lnd_response.json())

Solutions:

Macaroon Not Hex-Encoded

import codecs
with open('macaroon.dat', 'rb') as f:
    macaroon_hex = codecs.encode(f.read(), 'hex').decode()

Wrong Macaroon File

Use admin.macaroon for most operations, not readonly.macaroon or invoice.macaroon.

Macaroon Expired/Revoked

Create a new macaroon using LND's native API directly:

# curl - Bake new macaroon via LND REST API
# Replace {API_ENDPOINT} with node's api_endpoint
curl -X POST "https://{API_ENDPOINT}/v1/macaroon" \
  -H "Grpc-Metadata-macaroon: {EXISTING_ADMIN_MACAROON_HEX}" \
  -d '{"permissions": [{"entity": "info", "action": "read"}, {"entity": "invoices", "action": "read"}, {"entity": "invoices", "action": "write"}]}'

# Python
import requests

# Get node endpoint first
node_response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
api_endpoint = node_response.json()['api_endpoint']

# Bake new macaroon
response = requests.post(
  f"https://{api_endpoint}/v1/macaroon",
  headers={'Grpc-Metadata-macaroon': EXISTING_ADMIN_MACAROON_HEX},
  json={
    "permissions": [
      {"entity": "info", "action": "read"},
      {"entity": "invoices", "action": "read"},
      {"entity": "invoices", "action": "write"}
    ]
  }
)
new_macaroon = response.json()
print(f"New macaroon: {new_macaroon['macaroon']}")

Invalid Macaroon

Re-download macaroon from the provisioning API. TLS certificates are managed automatically by the platform - no certificate files are required for API calls:

# curl - Re-download macaroon
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/macaroon/admin" \
  -H "Authorization: Bearer {AUTH_TOKEN}" \
  -o

# Python
import requests

response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/macaroon/admin",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
macaroon_data = response.json()
# Save and decrypt macaroon

"Permission Denied"

Symptoms: Auth succeeds but operations fail

Diagnostics:

To check macaroon permissions, use LND's native API or decode the macaroon. Note: Macaroon permissions are determined when it's created.

Solutions:

Create Macaroon with Required Permissions

Create a macaroon with specific permissions using LND's native API:

# curl - Bake macaroon with specific permissions
curl -X POST "https://{API_ENDPOINT}/v1/macaroon" \
  -H "Grpc-Metadata-macaroon: {ADMIN_MACAROON_HEX}" \
  -d '{
    "permissions": [
      {"entity": "info", "action": "read"},
      {"entity": "invoices", "action": "read"},
      {"entity": "invoices", "action": "write"},
      {"entity": "offchain", "action": "read"},
      {"entity": "offchain", "action": "write"}
    ]
  }'

# Python
import requests

permissions = [
    {"entity": "info", "action": "read"},
    {"entity": "invoices", "action": "read"},
    {"entity": "invoices", "action": "write"},
    {"entity": "offchain", "action": "read"},
    {"entity": "offchain", "action": "write"}
]

response = requests.post(
  f"https://{API_ENDPOINT}/v1/macaroon",
  headers={'Grpc-Metadata-macaroon': ADMIN_MACAROON_HEX},
  json={"permissions": permissions}
)
new_macaroon = response.json()
print(f"New macaroon with custom permissions: {new_macaroon['macaroon']}")

Use Admin Macaroon

For full access, use admin.macaroon.

SDK Installation Fails

Solutions:

Python Version (requires 3.8+)

python --version

Use Virtual Environment

python -m venv comet-env
source comet-env/bin/activate  # Linux/Mac

Install from GitHub

pip install git

Slow API Response Times

Symptoms: API calls >1 second, timeouts

Diagnostics:

Measure API response times:

# Python - Measure API response time
import requests
import time

start = time.time()
response = requests.get(
  f"https://{API_ENDPOINT}/v1/getinfo",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX}
)
elapsed_ms = (time.time() - start) * 1000
print(f"API call took: {elapsed_ms:.2f}ms")
print(f"Response: {response.json()}")

// JavaScript - Measure API response time
const start = performance.now();
const response = await fetch(`https://${API_ENDPOINT}/v1/getinfo`, {
  method: 'GET',
  headers: { 'Grpc-Metadata-macaroon': MACAROON_HEX }
});
const elapsedMs = performance.now() - start;
const data = await response.json();
console.log(`API call took: ${elapsedMs.toFixed(2)}ms`);
console.log('Response:', data);

Check node status and tier via provisioning API:

# curl
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '{status, tier}'

Solutions:

Node Resource Exhausted (>80% CPU/memory)

Node tier upgrades can be done through the dashboard or by contacting support. Check current tier:

# curl
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '.tier'

Network Latency

Measure latency to node endpoint and check node region. To create a node closer to your application, use the provisioning API:

# Measure latency to node endpoint
time curl -X GET "https://{API_ENDPOINT}/v1/getinfo" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" > /dev/null

# Check current node region
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '.region'

# Python - Create node in specific region
import requests

node_data = {
  "name": "My New Node",
  "network": "testnet",
  "node_tier": "standard",
  "node_type": "LND",
  "region": "us-west-2",
  "settings": {
    "alias": "MyNode",
    "grpc": True,
    "rest": True
  }
}

response = requests.post(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"},
  json=node_data
)
print(response.json())

Database Compaction

Database compaction operations require support assistance. Contact support@cometcash.com if you experience database performance issues.

Optimize Queries

# Use specific queries
channels = node.channels.list(active_only=True, limit=10)
# Instead of: all_channels = node.channels.list()

Credit and Billing

Unexpected Credit Consumption

Diagnostics:

List all nodes to see what's consuming credits:

# curl - List all nodes
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Python
import requests

response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
nodes = response.json()
running_nodes = [n for n in nodes if n['status'] == 'running']
print(f"Running nodes: {len(running_nodes)}")
for node in running_nodes:
    print(f"  - {node['node_name']} ({node['node_id']}) - Tier: {node['tier']}")

Note: Billing and credit breakdown details are available through the dashboard.

Common Causes:

Forgot to Delete Test Nodes

List and delete nodes:

# curl - List nodes
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Delete node
curl -X DELETE "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Python
import requests

# List nodes
response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
nodes = response.json()

# Delete test nodes
for node in nodes:
    if 'test' in node['node_name'].lower():
        delete_response = requests.delete(
          f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{node['node_id']}",
          headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
        )
        print(f"Deleted: {node['node_name']}")

Running Higher Tier Than Needed

Node tier changes require dashboard access or support assistance. Check current tier:

# curl
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '.tier'

Use the dashboard to downgrade node tiers, or contact support for assistance.

Supporting Infrastructure

LND nodes consume credits for Bitcoin infrastructure (pruned node + shared full node). See Pricing & Credits.

Billing Discrepancies

Diagnostics:

Billing invoices and subscription details are available through the dashboard. Contact billing@cometcash.com for API access to billing information.

Common Causes:

Mid-cycle upgrade: Prorated charge for remaining period
Tax not accounted for: Invoices include VAT/GST
Multiple organizations: Each billed separately

Contact billing@cometcash.com with invoice ID for discrepancies.

Cannot Change Subscription Tier

Cannot Downgrade - Too Many Resources

Check node list and delete unused nodes to free credits:

# curl - List nodes
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Delete node to free credits
curl -X DELETE "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

Credit consumption details are available through the dashboard.

Payment Method Declined

Payment method management is available through the dashboard. Visit Dashboard → Billing → Payment Methods to update or add payment methods including Bitcoin/Lightning.

Timing:

Downgrades: Effective next billing cycle
Upgrades: Immediate

Node-Specific Issues

Tapd: Asset Issuance Fails

Diagnostics:

First, get the node's API endpoint from provisioning API, then use Tapd's native REST API:

# Get node endpoint
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq -r '.api_endpoint'

# Check Tapd balance (replace {API_ENDPOINT} with actual endpoint)
curl -X GET "https://{API_ENDPOINT}/v1/taproot-assets/assets/balance" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Get universe info
curl -X GET "https://{API_ENDPOINT}/v1/taproot-assets/universe/info" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Python
import requests

# Get node endpoint
node_response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
api_endpoint = node_response.json()['api_endpoint']

# Check Tapd balance
balance_response = requests.get(
  f"https://{api_endpoint}/v1/taproot-assets/assets/balance",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX}
)
print(f"Balance: {balance_response.json()}")

# Get universe info
universe_response = requests.get(
  f"https://{api_endpoint}/v1/taproot-assets/universe/info",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX}
)
print(f"Universe info: {universe_response.json()}")

# Note: Detailed logs are available through the dashboard

Solutions:

Insufficient Balance

Fund the Tapd node using LND's wallet or Lightning network. First get a wallet address from LND, then send funds:

# Get new address from LND
curl -X GET "https://{API_ENDPOINT}/v1/newaddress?type=WITNESS_PUBKEY_HASH" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Send funds to that address, then check balance
curl -X GET "https://{API_ENDPOINT}/v1/taproot-assets/assets/balance" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

Invalid Metadata

Valid JSON required
Size <4KB
Escape special characters

Fee Rate Too Low

Mint assets with appropriate fee rate using Tapd's native API:

# Mint asset with fee rate (replace {API_ENDPOINT} with node's api_endpoint)
curl -X POST "https://{API_ENDPOINT}/v1/taproot-assets/assets/mint" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": {
      "asset_name": "My Asset",
      "asset_type": "NORMAL",
      "amount": "1000"
    },
    "fee_rate": 10
  }'

# Python
import requests

mint_data = {
    "asset": {
        "asset_name": "My Asset",
        "asset_type": "NORMAL",
        "amount": "1000"
    },
    "fee_rate": 10
}

response = requests.post(
  f"https://{API_ENDPOINT}/v1/taproot-assets/assets/mint",
  headers={
    'Grpc-Metadata-macaroon': MACAROON_HEX,
    'Content-Type': 'application/json'
  },
  json=mint_data
)
print(response.json())

Tapd: Universe Sync Failing

Diagnostics:

List universe federation servers and test connectivity:

# List universe federation servers
curl -X GET "https://{API_ENDPOINT}/v1/taproot-assets/universe/federation/servers" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Query universe server
curl -X GET "https://{API_ENDPOINT}/v1/taproot-assets/universe/stats?asset_name={ASSET_NAME}" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Python
import requests

# List federation servers
servers_response = requests.get(
  f"https://{API_ENDPOINT}/v1/taproot-assets/universe/federation/servers",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX}
)
print("Federation servers:", servers_response.json())

# Query universe stats
stats_response = requests.get(
  f"https://{API_ENDPOINT}/v1/taproot-assets/universe/stats?asset_name={ASSET_NAME}",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX}
)
print("Universe stats:", stats_response.json())

Solutions:

Add Alternative Servers

Add universe federation servers using Tapd's native API:

# Add universe federation server
curl -X POST "https://{API_ENDPOINT}/v1/taproot-assets/universe/federation/add" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "servers": [{
      "host": "universe-backup.example.com",
      "id": "universe-backup"
    }]
  }'

# Python
import requests

add_server_data = {
    "servers": [{
        "host": "universe-backup.example.com",
        "id": "universe-backup"
    }]
}

response = requests.post(
  f"https://{API_ENDPOINT}/v1/taproot-assets/universe/federation/add",
  headers={
    'Grpc-Metadata-macaroon': MACAROON_HEX,
    'Content-Type': 'application/json'
  },
  json=add_server_data
)
print(response.json())

Force Sync

Sync universe using Tapd's native API:

# Sync universe (replace {ASSET_NAME} with your asset name or use asset_id)
curl -X POST "https://{API_ENDPOINT}/v1/taproot-assets/universe/sync" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "universe_host": "universe.example.com",
    "asset_name": "{ASSET_NAME}",
    "sync_mode": "SYNC_ISSUANCE_ONLY"
  }'

# Python
import requests

sync_data = {
    "universe_host": "universe.example.com",
    "asset_name": ASSET_NAME,
    "sync_mode": "SYNC_ISSUANCE_ONLY"
}

response = requests.post(
  f"https://{API_ENDPOINT}/v1/taproot-assets/universe/sync",
  headers={
    'Grpc-Metadata-macaroon': MACAROON_HEX,
    'Content-Type': 'application/json'
  },
  json=sync_data
)
print(response.json())

LND: Channel Opening Fails

Symptoms: Never confirms, stuck in "pending"

Diagnostics:

Check balance, peers, and pending channels using LND's native REST API:

# Get node endpoint first
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq -r '.api_endpoint'

# Check wallet balance
curl -X GET "https://{API_ENDPOINT}/v1/balance/blockchain" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# List peers
curl -X GET "https://{API_ENDPOINT}/v1/peers" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# List pending channels
curl -X GET "https://{API_ENDPOINT}/v1/channels/pending" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Python
import requests

# Get node endpoint
node_response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
api_endpoint = node_response.json()['api_endpoint']

auth_headers = {
  'Grpc-Metadata-macaroon': MACAROON_HEX
}

# Check balance
balance = requests.get(
  f"https://{api_endpoint}/v1/balance/blockchain",
  headers=auth_headers
).json()
print(f"Balance: {balance}")

# List peers
peers = requests.get(
  f"https://{api_endpoint}/v1/peers",
  headers=auth_headers
).json()
print(f"Peers: {peers}")

# Pending channels
pending = requests.get(
  f"https://{api_endpoint}/v1/channels/pending",
  headers=auth_headers
).json()
print(f"Pending channels: {pending}")

Solutions:

Peer Not Connected

Connect to peer and open channel using LND's native API:

# Connect to peer
curl -X POST "https://{API_ENDPOINT}/v1/peers" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "addr": {
      "pubkey": "03abc...",
      "host": "host:port"
    }
  }'

# Open channel
curl -X POST "https://{API_ENDPOINT}/v1/channels" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "node_pubkey_string": "03abc...",
    "local_funding_amount": "1000000",
    "push_sat": "0",
    "sat_per_byte": "1"
  }'

# Python
import requests

# Connect to peer
connect_data = {
    "addr": {
        "pubkey": "03abc...",
        "host": "host:port"
    }
}
requests.post(
  f"https://{API_ENDPOINT}/v1/peers",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX},
  json=connect_data
)

# Open channel
channel_data = {
    "node_pubkey_string": "03abc...",
    "local_funding_amount": "1000000",
    "push_sat": "0",
    "sat_per_byte": "1"
}
response = requests.post(
  f"https://{API_ENDPOINT}/v1/channels",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX},
  json=channel_data
)
print(response.json())

Fee Rate Too Low

Open channel with higher fee rate:

# Open channel with specific fee rate
curl -X POST "https://{API_ENDPOINT}/v1/channels" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "node_pubkey_string": "03abc...",
    "local_funding_amount": "1000000",
    "push_sat": "0",
    "sat_per_byte": "20"
  }'

# Python
import requests

channel_data = {
    "node_pubkey_string": "03abc...",
    "local_funding_amount": "1000000",
    "push_sat": "0",
    "sat_per_byte": "20"  # Higher fee rate
}

response = requests.post(
  f"https://{API_ENDPOINT}/v1/channels",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX},
  json=channel_data
)
print(response.json())

Stuck Pending Channel (>24 hours)

Abandon a stuck pending channel. ⚠️ Warning: Only for truly stuck channels. Funds may be lost.

# Abandon channel
curl -X POST "https://{API_ENDPOINT}/v1/channels/abandonchannel" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_point": {
      "funding_txid_str": "abc",
      "output_index": 0
    }
  }'

# Python
import requests

abandon_data = {
    "channel_point": {
        "funding_txid_str": "abc",
        "output_index": 0
    }
}

response = requests.post(
  f"https://{API_ENDPOINT}/v1/channels/abandonchannel",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX},
  json=abandon_data
)
print(response.json())

LND: Routing Failures

Symptoms: "No route found", high failure rate

Diagnostics:

Check channel balance, list channels, and query routes:

# Get channel balance
curl -X GET "https://{API_ENDPOINT}/v1/balance/channels" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# List channels
curl -X GET "https://{API_ENDPOINT}/v1/channels" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Query routes
curl -X GET "https://{API_ENDPOINT}/v1/graph/routes/{03xyz...}/10000" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}"

# Python
import requests

auth_headers = {'Grpc-Metadata-macaroon': MACAROON_HEX}

# Channel balance
balance = requests.get(
  f"https://{API_ENDPOINT}/v1/balance/channels",
  headers=auth_headers
).json()

# List channels
channels = requests.get(
  f"https://{API_ENDPOINT}/v1/channels",
  headers=auth_headers
).json()
active_channels = [c for c in channels['channels'] if c['active']]
print(f"Active channels: {len(active_channels)}")

# Query routes
routes = requests.get(
  f"https://{API_ENDPOINT}/v1/graph/routes/{DEST_PUBKEY}/10000",
  headers=auth_headers
).json()
print(f"Routes found: {len(routes.get('routes', []))}")

Solutions:

Insufficient Local Balance

Rebalance channels using LND's native API:

# Rebalance channels (using LND's circular rebalance or manual rebalancing)
# Note: LND doesn't have a direct rebalance endpoint, so use circular rebalancing via payment
curl -X POST "https://{API_ENDPOINT}/v1/channels/rebalance" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "outgoing_chan_id": "123456",
    "last_hop_pubkey": "...",
    "amt": "100000",
    "max_fee": "1000"
  }'

Alternatively, use circular payment routing or external tools for channel rebalancing.

Poor Network Connectivity

Open channel with well-connected peer:

# Connect and open channel with well-connected node
curl -X POST "https://{API_ENDPOINT}/v1/peers" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "addr": {
      "pubkey": "03WELL_CONNECTED_NODE...",
      "host": "host:port"
    }
  }'

curl -X POST "https://{API_ENDPOINT}/v1/channels" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "node_pubkey_string": "03WELL_CONNECTED_NODE...",
    "local_funding_amount": "5000000"
  }'

Payment Too Large

Send payment with multiple parts (MPP - Multi-Path Payments):

# Send payment with MPP
curl -X POST "https://{API_ENDPOINT}/v2/router/send" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_request": "lnbc1...",
    "max_parts": 5,
    "timeout_seconds": 60
  }'

# Python
import requests

payment_data = {
    "payment_request": PAYMENT_REQUEST,
    "max_parts": 5,
    "timeout_seconds": 60
}

response = requests.post(
  f"https://{API_ENDPOINT}/v2/router/send",
  headers={'Grpc-Metadata-macaroon': MACAROON_HEX},
  json=payment_data
)
print(response.json())

Bitcoin Core: Sync Delays

Diagnostics:

Bitcoin Core uses JSON-RPC protocol (not REST). Get node endpoint first, then use JSON-RPC:

# Get node endpoint
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq -r '.api_endpoint'

# Get blockchain info (JSON-RPC)
curl -X POST "http://{API_ENDPOINT}:18449" \
  --user "polaruser:polarpass" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "getblockchaininfo",
    "params": []
  }'

# Get peer info
curl -X POST "http://{API_ENDPOINT}:18449" \
  --user "polaruser:polarpass" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "getpeerinfo",
    "params": []
  }'

# Python - Bitcoin Core JSON-RPC
import requests
import json

# Get node endpoint
node_response = requests.get(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
api_endpoint = node_response.json()['api_endpoint']

# JSON-RPC call
rpc_url = f"http://{api_endpoint}:18449"
rpc_auth = ("polaruser", "polarpass")  # Default credentials - check your node config

def bitcoin_rpc(method, params=[]):
    payload = {
        "jsonrpc": "1.0",
        "id": "pythontest",
        "method": method,
        "params": params
    }
    response = requests.post(
      rpc_url,
      auth=rpc_auth,
      headers={"Content-Type": "application/json"},
      json=payload
    )
    return response.json()['result']

# Get blockchain info
blockchain_info = bitcoin_rpc("getblockchaininfo")
print(f"Block height: {blockchain_info['blocks']}")
print(f"Sync progress: {blockchain_info['verificationprogress']}")

# Get peer info
peers = bitcoin_rpc("getpeerinfo")
print(f"Connected peers: {len(peers)}")

Solutions:

Increase Connection Limit

Bitcoin Core configuration changes require support assistance or dashboard access. Contact support for configuration changes like increasing maxconnections.

Disconnect Slow Peers

Disconnect nodes and add seed nodes using JSON-RPC:

# Disconnect node
curl -X POST "http://{API_ENDPOINT}:18449" \
  --user "polaruser:polarpass" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "disconnectnode",
    "params": ["1.2.3.4"]
  }'

# Add node
curl -X POST "http://{API_ENDPOINT}:18449" \
  --user "polaruser:polarpass" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "addnode",
    "params": ["seed.bitcoin.sipa.be", "add"]
  }'

# Python
# Disconnect node
bitcoin_rpc("disconnectnode", ["1.2.3.4"])

# Add node
bitcoin_rpc("addnode", ["seed.bitcoin.sipa.be", "add"])

Bitcoin Core: RPC Errors

Solutions:

Check Status

Check Bitcoin Core status and restart node:

# Get blockchain info to check status
curl -X POST "http://{API_ENDPOINT}:18449" \
  --user "polaruser:polarpass" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "getblockchaininfo",
    "params": []
  }'

# Restart node via provisioning API
curl -X POST "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/stop" \
  -H "Authorization: Bearer {AUTH_TOKEN}"
# Wait a moment, then start
curl -X POST "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/start" \
  -H "Authorization: Bearer {AUTH_TOKEN}"

# Python
# Check Bitcoin Core status
status = bitcoin_rpc("getblockchaininfo")
print(f"Status: {status}")

# Restart node
import time
requests.post(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/stop",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)
time.sleep(5)
requests.post(
  f"https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}/start",
  headers={"Authorization": f"Bearer {AUTH_TOKEN}"}
)

RPC Credentials

Comet manages credentials automatically. Check logs for authentication errors.

API and SDK Issues

429 Too Many Requests

Solution: Exponential Backoff

import time

def api_call_with_retry(func, max_retries=5):
    for i in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait = 2 ** i
            time.sleep(wait)
    raise Exception("Max retries exceeded")

503 Service Unavailable

Solutions:

Wait 1-2 minutes and retry
Check node status in dashboard
Implement retry logic

500 Internal Server Error

Solutions:

Check status.comet.platform
Review recent API changes
Contact support with request ID

Rate Limiting

Current Limits:

API Gateway: 100 requests/second per account
Per-node: 50 requests/second
Batch operations: 10 requests/second

Solutions:

Request Batching

# Instead of 100 individual calls:
node.send_payments_batch(payments)  # 1 API call

Cache Responses

from cachetools import TTLCache, cached

cache = TTLCache(maxsize=100, ttl=60)

@cached(cache)
def get_channel_list(node_id):
    return node.channels.list()

Request Higher Limits

Enterprise tier can request increases. Contact support@cometcash.com

Performance Optimization

Identifying Bottlenecks

Measure Performance:

import time
start = time.time()
response = node.get_info()
print(f"API call: {(time.time() - start)*1000:.2f}ms")

Check Metrics:

Node metrics are available through the dashboard. Check node status and command history via API:

# Get node details including command history
curl -X GET "https://provisioning.cometplatform.com/api/company/{COMPANY_ID}/nodes/{NODE_ID}" \
  -H "Authorization: Bearer {AUTH_TOKEN}" | jq '{status, tier, command_history}'

Common Bottlenecks:

Network latency (high ping)
Node resource exhaustion
Inefficient queries
Database size

Resource Optimization

Storage:

Database compaction requires support assistance. For LND nodes, delete old payment data using LND's native API:

# Delete payments (using LND API)
# Note: LND doesn't have a direct "delete payments before date" endpoint
# You'll need to list payments and delete individually, or use LND's native commands
curl -X GET "https://{API_ENDPOINT}/v1/payments" \
  -H "Grpc-Metadata-macaroon: {MACAROON_HEX}" \
  | jq '.payments[] | select(.creation_date < (now - 2592000)) | .payment_hash'

Logs are available through the dashboard. Database compaction operations require contacting support.

Configuration Tuning:

Node configuration changes require dashboard access or support assistance. Contact support for configuration tuning like dbcache, maxconnections, or LND-specific settings.

For LND node configuration, check current settings via LND's native API if available, but most configuration requires node restart with new settings, which should be done through support or dashboard.

Troubleshooting & Solutions

Troubleshooting & Solutions

Table of Contents