Skip to content

Tools API ​

deadhop is an MCP server reached over Nostr with ContextVM. Any MCP client that speaks the ContextVM transport can call it. Results come back as MCP structuredContent that matches each tool's published output schema.

Connecting ​

You need the service's public key (<data dir>/server.pubkey) and its relay list. With the TypeScript SDK:

ts
import { Client } from '@contextvm/mcp-sdk/client/index.js';
import { EncryptionMode, NostrClientTransport, PrivateKeySigner } from '@contextvm/sdk';

const transport = new NostrClientTransport({
  signer: new PrivateKeySigner(myHexSecretKey),
  relayHandler: ['wss://relay.one.example'],
  serverPubkey: SERVICE_PUBKEY_HEX,
  encryptionMode: EncryptionMode.REQUIRED, // the service refuses plaintext
});
const client = new Client({ name: 'my-shop', version: '1.0.0' });
await client.connect(transport);

const info = await client.callTool({ name: 'get_info', arguments: {} });

A non-operator calling create_invoice must mine NIP-13 proof of work into the signed request event: add a ["nonce", "<counter>", "<target bits>"] tag and vary the counter until the event id has at least pow_bits leading zero bits. The dashboard's src/lib/pow.ts is a working implementation that wraps any signer.

Tools ​

All inputs reject unknown fields.

get_info ​

Anyone. No arguments. Returns the service parameters for this caller.

FieldTypeMeaning
name, versionstringService name and version
networkstringbitcoin, testnet, signet or regtest
public_invoicingbooleanWhether non-operators may create invoices
pow_bitsintegerRequired proof of work for non-operators
pow_window_secsintegerAccepted age of a request event
min_confirmationsintegerConfirmations before confirmed
default_expiry_secsintegerLifetime when none is requested
max_expiry_secsintegerLongest lifetime this caller may request
min_amount_sat, max_amount_satintegerAmount bounds
is_adminbooleanWhether the caller is an operator

create_invoice ​

Operators, and the public when public_invoicing is on (with proof of work).

ArgumentTypeMeaning
amount_satinteger, requiredAmount in satoshis, within the bounds above
memostring, optionalNote stored with the invoice, at most 200 characters, no control or invisible characters
expiry_secsinteger, optionalLifetime in seconds, from 60 up to max_expiry_secs

Returns an Invoice:

FieldTypeMeaning
idstring32 lowercase hex characters (128 random bits). Whoever holds it can read the invoice.
addressstringFresh native segwit address
amount_satintegerRequested amount
memostringNote, empty if none
statusstringpending, detected, confirmed or expired
received_satintegerTotal seen, confirmed or not
confirmed_satintegerTotal with enough confirmations
created_at, expires_atintegerUnix seconds
settled_atinteger or nullWhen it became confirmed
bip21stringbitcoin: URI with address and amount
confirmations_requiredintegerConfirmations this invoice needs

get_invoice ​

Anyone holding the id. Argument: id (32 lowercase hex characters). Returns an Invoice.

list_invoices ​

Operators only. Newest first.

ArgumentTypeMeaning
statusstring, optionalOnly invoices in this state
beforeinteger, optionalOnly derivation indices below this (pagination cursor)
limitinteger, optionalPage size, 1 to 200, default 50

Returns { invoices, next_before }. Each entry is an Invoice plus index (derivation index) and creator (hex key that created it). Pass next_before as before for the next page; it is absent on the last page.

get_stats ​

Operators only. No arguments.

FieldTypeMeaning
pending, detected, confirmed, expiredintegerInvoice counts per state
confirmed_sat, detected_satintegerAmounts in those states
next_indexintegerNext derivation index
tip_heightinteger or nullLast chain tip seen
last_poll_atinteger or nullUnix seconds of the last poll
chain_okbooleanWhether the last poll reached the chain backend
watch_errorsintegerInvoices that could not be read in the last poll

Management tools ​

Operators only. Every tool that changes something needs a fresh request event addressed to this service that was never used before (ids are remembered across restarts) and is recorded in the audit log.

ToolArgumentsReturns
get_healthnoneservice (version, start, uptime, online since, paused, restarts), relays (url, status, connected), proxy (password hidden), chain, database (integrity, size, invoices, backups), warnings
get_metricsnoneaddresses_created, invoices, payments, received_sat, windows for 24h, 7d, 30d, 365d with available (false until the service has been online that long), sweep status
get_payment_seriesrange: day, week, month or yearpoints of { start, count, sat }: 24 hourly, 7 or 30 daily, or 52 weekly buckets, gap-filled
get_settingsnonesettings (live), defaults (environment), overridden (names), fixed (host-only values), operators, restart_pending, warnings
update_settingspatch: only the settings to change; sweep may be partial; proxy: "" turns the proxy offSame as get_settings
reset_settingsnoneSame as get_settings
add_operatorpubkey (hex, npub or nprofile), optional labelSame as get_settings
remove_operatorpubkeySame as get_settings; environment keys are refused
control_serviceaction: stop (refuse new invoices), start, restart (reconnect relays in-process){ paused, restart_pending }
backup_databasenone{ file, size_bytes, created_at }, written to <data dir>/backups
wipe_databaseconfirm: "WIPE", optional include_settings, force{ deleted, backup }
get_audit_logoptional limit (1 to 200)entries of { at, actor, action, detail }

Settings that can be patched: name, relays, public_invoicing, pow_bits, pow_window_secs, min_confirmations, default_expiry_secs, max_expiry_secs, min_amount_sat, max_amount_sat, max_open_invoices, max_invoices_per_day, rate_global_per_min, rate_per_key_per_min, rate_requests_per_min, rate_requests_per_key_per_min, poll_secs, late_grace_secs, proxy and sweep (enabled, mode = payjoin or coinjoin, threshold_sat, max_fee_rate_sat_vb, min_anonymity_set). Unknown fields are refused.

A request sent while the service is reconnecting is not answered; clients should time out and retry.

Errors ​

Errors are JSON-RPC errors with a stable data.code. Internal error text never reaches the caller.

JSON-RPC codedata.codeMeaning
-32602invalid_paramsArguments out of range or malformed
-32001unauthorizedOperator-only tool, or public invoicing is off
-32002not_foundNo invoice with that id
-32003pow_rejectedMissing or insufficient work, stale, replayed or not addressed to this service
-32004rate_limitedA rate limit was hit; retry later
-32005capacityOpen-invoice or daily cap reached
-32006pausedInvoicing is stopped by an operator
-32603internalSomething failed on the service side

Arguments that do not match the input schema at all (wrong types, unknown fields) come back as a tool result with isError: true rather than a JSON-RPC error.

deadhop 0.1.0 · Every page is also available as Markdown: replace .html with .md.