Input & Output
The shared config-key pattern, credential resolution, and how errors surface
Shared Input Pattern
Every operation on this node takes the same three top-level config keys, plus its own operation-specific fields:
| Key | Required | Description |
|---|---|---|
resource | ✓ Yes | One of address, transaction, block, mempool, fee, psbt, wallet. |
operation | ✓ Yes | The operation within that resource, e.g. getUtxos. |
network | Reads: No · Writes/signing: ✓ Yes | mainnet | testnet | signet | regtest. Read operations default to Bitcoin:DefaultNetwork when omitted; every write/signing operation requires it explicitly. |
Everything else is specific to the chosen resource + operation pair — see that resource's page for the exact field list.
Credential Fields (Signing Operations Only)
psbt/sign, wallet/deriveAddress (non-watch-only), and
wallet/signMessage share this small set of credential-related fields:
| Field | Type | Description |
|---|---|---|
walletType | select | readOnly (no signing, default), wif, or mnemonic. |
credentialID | number | Vault reference resolved to a raw CryptoWalletRecord — never a plain config field. WIF credentials use .PrivateKey; mnemonic credentials use .SeedPhrase. |
addressType | select | p2wpkh (BIP-84, default) or p2tr (BIP-86). wallet/signMessage only accepts p2wpkh. |
derivationPath | text | Overrides the network-appropriate SLIP-44 default — see Networks. |
Key material is never a config field. WIF keys and BIP-39 mnemonics live only in the
vault, referenced by
credentialID. No operation's config-echo (the workflow-state dictionary
each operation writes for observability) ever includes the raw secret — only non-secret metadata like
the resolved address or derivation path.
Shared Output Shape
A successful call returns a JSON object whose shape is documented on each operation's page. Most
block, several transaction/mempool operations return the underlying
Esplora API's own JSON response as-is (no hand-modeled wrapper) rather than a fixed schema — check the
actual response when in doubt.
How Errors Surface
| Situation | What happens |
|---|---|
Unknown/unconfigured network | Node throws BitcoinInvalidNetworkException before any HTTP call is made. |
| Esplora returns 404 (address/tx/block doesn't exist) | Surfaces as a node-level error result — check the id/hash and network are correct. |
| Esplora returns 400/422 (malformed input) | Surfaces as a validation-style error, e.g. VAL_MISSING_ADDRESS / VAL_MISSING_TXID. |
| Esplora rate limiting (429) | The node's EsploraRateLimitHandler retries automatically with backoff. See Troubleshooting. |
| Missing/invalid credential on a signing operation | WALLET_CREDENTIAL_NOT_FOUND or WALLET_INVALID_KEY_MATERIAL — see Troubleshooting. |
psbt/sign outputs don't match expectedOutputs[] | PSBT_OUTPUT_MISMATCH — the operation refuses to sign. See PSBT Signing Pipeline. |
| A UTXO was spent elsewhere between build and finalize | PSBT_UTXO_NO_LONGER_AVAILABLE — Bitcoin's own consensus rules prevented the double-spend; this error just reports it. |
Reads are idempotent; writes are not automatically so. Every
address,
block, mempool, fee, and non-broadcast transaction
operation is a pure read — safe to call repeatedly. transaction/broadcast is the one
exception that treats a lost-response retry as an idempotent success (alreadyKnown: true)
rather than an error. psbt/build supports an idempotencyKey for safe retries of
the build step itself.