XChain Platform Encoder: API Reference

Overview

The encoder is a stateless JSON-RPC 2.0 service that builds unsigned PSBTs embedding XChain ACTION payloads into Bitcoin, Litecoin, and Dogecoin transactions. It holds no database and no state between calls: the caller supplies the inputs, the encoder returns an unsigned PSBT, and the caller signs and broadcasts.

All methods are called via HTTP POST to the service root (/) using the JSON-RPC 2.0 envelope:

curl -X POST https://encoder.xchain.io/BTC/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"ping","id":1}'

A machine-readable OpenRPC 1.3.2 spec for every method is served at GET /openrpc.json. It can be loaded into OpenRPC tooling or the xchain-sdk.

Base URL

One encoder instance runs per chain. The public deployment is path-routed by coin prefix:

https://encoder.xchain.io/{COIN}/

Self-hosted instances bind a single network (set by NETWORK) and are reached directly at http://{host}:{port}/. Regtest instances follow the same JSON-RPC contract.

Authentication

Auth is optional. When the operator sets an API_KEY, requests must carry a matching x-api-key header; the public instances run open. See Configuration for the relevant variables.

Error codes

Errors follow JSON-RPC 2.0, returning an error object with a numeric code and a message:

The full registry is documented at Error Codes.

Methods

ping

Health check. Takes no parameters.

Request:

{"jsonrpc":"2.0","method":"ping","id":1}

Response:

{"status":"success","version":"1.8.0"}

estimate_fee

Suggested fee tiers in base units per vByte (satoshis on Bitcoin, litoshis on Litecoin, koinu on Dogecoin), sourced from the coin node’s estimatesmartfee. Takes no parameters.

Request:

{"jsonrpc":"2.0","method":"estimate_fee","id":1}

Response:

{"low":4,"medium":8,"high":15}

create_tx

Build an unsigned PSBT that embeds an XChain ACTION payload. The caller signs the returned PSBT and broadcasts it (directly or via broadcast_tx).

The encoder auto-selects the encoding format by payload size: OP_RETURN for payloads of 76 bytes or fewer, otherwise P2SH. The P2SH and P2WSH formats use a two-transaction flow: call create_tx once to build the funding transaction, then call it again with p2shHash and p2shHex set to build the reveal transaction. rawData is decoded as Latin-1 so arbitrary bytes round-trip losslessly. Dogecoin has no SegWit, so P2WSH is rejected on DOGE networks.

Parameters:

A UTXO object has the shape:

{
  "txid": "64-char hex string",
  "vout": 0,
  "value": 100000,
  "scriptPubKey": "hex"
}

Request:

{
  "jsonrpc": "2.0",
  "method": "create_tx",
  "params": {
    "pubkey": "bc1qexampleaddress",
    "data": "SEND|0|JDOG|100|bc1qrecipient"
  },
  "id": 1
}

Response:

{
  "psbt": "70736274ff... (unsigned PSBT, hex, BIP 174)",
  "encoding": "OP_RETURN"
}

See Format Selection for the full size limits and auto-selection logic.

broadcast_tx

Broadcast a signed raw transaction to the coin node.

Parameters:

Request:

{"jsonrpc":"2.0","method":"broadcast_tx","params":{"tx_hex":"0200000001..."},"id":1}

Response:

{"txid":"64-char hex string"}

get_utxos

List the UTXOs for an address. The encoder proxies this to xchain-utxo-tracker; it is a convenience for callers that do not run their own tracker client.

Parameters:

Request:

{"jsonrpc":"2.0","method":"get_utxos","params":{"address":"bc1qexampleaddress"},"id":1}

Response:

[
  {
    "txid": "64-char hex string",
    "vout": 0,
    "value": 100000,
    "scriptPubKey": "hex"
  }
]

Related

• Encoder overview: features, encoding process, configuration, and testing
• Format Selection: decision guide and size limits for each encoding format
• API Reference (all services): the platform-wide REST and JSON-RPC entry point
• UTXO Tracker: the service that supplies UTXOs to the encoder
• SDK: developer SDK that wraps these methods with typed helpers

Copyright © 2025-2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.