XChain Platform - Software Developer Kit (SDK)

Developer-facing SDK for the XChain Platform: generate XChain transactions and query blockchain data.

Features

• 31 ACTION types: sdk.send(), sdk.issue(), sdk.mint(), sdk.stake(), and 27 more convenience methods
• Transaction lifecycle: sdk.submitAction() handles the full encode -> sign -> broadcast -> wait pipeline in one call
• Wallet sessions: sdk.session(wif) bundles address/key/UTXO state for repeated actions from one address
• Fee estimation: sdk.estimateFees() returns fee info without signing or broadcasting
• UTXO chaining: in-memory UTXO cache prevents double-spend on rapid sequential transactions
• Workflow recipes: sdk.issueAndDistribute(), sdk.deployAndFund(), sdk.stakeAndDelegate(), and more
• Cross-chain helpers: coordinate swaps and parallel actions across BTC, LTC, and DOGE SDK instances
• Event-driven confirmation: sdk.waitForAction(txid) resolves when the indexer processes a transaction
• Interactive REPL: npm run repl drops into a live session with a pre-configured SDK instance
• Automatic format selection: picks the smallest encoding format for every action
• PSBT generation: integrates with xchain-encoder to produce unsigned transactions
• 115+ explorer query methods: balances, tokens, transactions, markets, history, contracts
• Batch builder: fluent API: await sdk.batch().send({...}).mint({...}).build() (build() is async)
• Real-time events: WebSocket streaming with onBlock(), onAction(), onAddress(), and more
• Encrypted messaging: ECIES, ECDH, and AES encryption for MESSAGE actions; messaging.send() accepts a Buffer payload and getMessages() exposes msg.bytes for binary ECIES
• Token-gated file publishing: sdk.gatedFile.encryptFileBytes() and sdk.gatedFile.encryptPack() produce AES-256-GCM ciphertext + key for FILE v1 gated content; key handoff as a compact 33-byte binary payload via serializeKeyPayload() / parseKeyPayload() (sent through ECIES in binary mode). See Token-Gated Content
• Attestation envelope helpers: AttestationHelpers.llm({...}) builds the JSON envelope a VM contract passes to xchain.attestation.request(...) with provider_id 'llm'; AttestationHelpers.httpGet({url}) validates the URL and returns the payload string for 'http_get'; AttestationHelpers.requestOptions({redundancy, deadlineBlocks}) builds the gateway options object. By design these are envelope builders only: there is no user-submittable ATTEST action. ATTEST v0 (request) and v1 (response) are VM-emitted: a contract calls xchain.attestation.request(...) and validators emit the on-chain attestation. So the SDK helps you shape the request a contract makes, and you read the results via getAttestations(). It does not (and cannot) encode an ATTEST action directly, the same way XCALL is VM-emission-only.
• Token-ownership trading helpers: ORDER/SWAP/DISPENSER v0 carry GIVE_OWNERSHIP / GET_OWNERSHIP flags; SWEEP carries independent ORDERS / SWAPS / DISPENSERS flags (was a single ESCROWS flag)
• HTTP 402 payments: X402Client and X402Gateway implement an XChain-native, x402-shaped pay-per-call flow over on-chain SEND actions, with xchain-send (pay-per-call), xchain-dispenser (hold-to-access), and xchain-deposit (metered spend ledger) schemes; fail-closed by default on maxAmount. See x402 Payments
• Contract-targeted staking: session.stakeToContract({ amount, signingPubkey, targetContractIndex, tick }), session.unstakeFromContract({...}), and session.delegateForContract({...}) emit STAKE v3 / UNSTAKE v1 / DELEGATE v1 against a smart contract deployed via DEPLOY v1 (with COOLDOWN_BLOCKS + SLASH_DESTINATION). High-level recipes: sdk.deployStakeableContract() and sdk.stakeToContractAndDelegate()
• NFT helpers: sdk.nft.unique(), sdk.nft.edition(), sdk.nft.collectionItem(), sdk.nft.attachContentParams(), and sdk.nft.isNft() for building the NFT pattern (ISSUE with DECIMALS=0 + LOCK_MAX_SUPPLY=1) plus high-level sdk.issueNft(), sdk.issueNftEdition(), sdk.issueCollectionItem(), and sdk.attachContent() submit recipes
• Project registry helpers: sdk.project.rosterParams() and sdk.project.rosterEditParams() build LIST actions for owner-attested token rosters; sdk.setRoster() runs LIST then LINK and waits for the indexer
• Ticker compaction: on by default; resolves token tickers to their compact ^id wire form via the explorer before encoding to shrink on-chain payload size; opt out with { compactTickers: false }
• MCP server: npx xchain-mcp exposes all explorer query tools as Model Context Protocol tools for AI agent use
• Wallet & auth: key management, PSBT signing, challenge-response verification
• Smart contracts: deploy, execute, deposit, withdraw via xchain-vm integration
• Hub discovery: auto-resolves service endpoints from xchain-hub
• Retry with backoff: handles HTTP 429/502/503/504, respects Retry-After headers
• Request hooks: onRequest, onResponse, onError, onRetry callbacks
• TypeScript definitions: full .d.ts for IDE autocomplete
• Browser bundle: Browserify build for client-side use

Documentation

Full SDK developer guide is published at docs.xchain.io/components/sdk:

| Document | Description | |---|---| | README | Overview, installation, usage modes | | Configuration | Constructor options, env vars, hub discovery, retry, pooling, hooks | | Actions | All 31 ACTION types: params, validation rules, format versions, examples | | Transaction Lifecycle | submitAction, fee estimation, UTXO chaining, P2SH two-phase handling | | Wallet Sessions | Bound wallet sessions, convenience methods, UTXO cache | | Workflows | High-level recipes: issueAndDistribute, deployAndFund, stakeAndDelegate | | Cross-Chain | Multi-chain coordination: parallel actions, swaps, links | | Explorer | All 115+ query methods: balances, tokens, transactions, markets | | Encoder | PSBT generation: encoding types, options, pre-flight validation, P2SH two-phase | | Batch Builder | Fluent API for multi-action transactions | | Contracts | VM smart contract integration: deploy, execute, deposit, withdraw | | WebSocket | Real-time event streaming: blocks, actions, addresses, markets | | Wallet & Auth | Key management, PSBT signing, challenge-response verification | | Messaging | ECIES/ECDH/AES encryption for MESSAGE actions | | Light Client (SPV) | Cryptographic balance/action verification against stake-weighted checkpoints | | NFT & Registry Builders | NFT pattern builders, collection/content attachment, project roster LIST/LINK | | Format Selection | How the SDK picks the optimal format version | | Errors | All error classes, codes, and troubleshooting | | Examples | End-to-end code examples |

Install

npm install @dankest-llc/xchain-sdk

Node 22 or newer. For development against the source, clone this repository and npm install inside it; the companion MCP server for AI agents is published separately as xchain-mcp.

Quick Start

const { XChainSDK } = require('@dankest-llc/xchain-sdk');

// Zero-config: a network alone targets the public XChain Platform.
// Mainnet/testnet default to the public hosts (hub.xchain.io discovers
// explorer/encoder, falling back to explorer.xchain.io / encoder.xchain.io);
// any *-regtest network defaults to localhost.
const sdk = new XChainSDK({ network: 'bitcoin-mainnet' });

// To point at your own services, pass full URLs (include the scheme; a
// bare host is treated as http://host:<dev-port>):
// const sdk = new XChainSDK({
//     network: 'bitcoin-mainnet',
//     explorerUrl: 'https://explorer.example.com',
//     encoderUrl:  'https://encoder.example.com'
// });

// Generate an action string
const result = await sdk.send({
    tick: 'MYTOKEN',
    amount: '100',
    destination: 'bc1q...',
    memo: 'Payment'
});
console.log(result.actionString); // 'SEND|0|MYTOKEN|100|bc1q...|Payment'

// Multi-destination SEND: one entry per recipient. The wire format version
// is chosen from the legs (v1 shared tick, v2 per-leg tick, v3 per-leg memo).
// A flat {tick, amount, destination} map can only ever express ONE leg, so
// the SDK refuses one against a multi-leg format instead of repeating leg 1.
const multi = await sdk.send({
    tick: 'MYTOKEN',
    legs: [
        { amount: '100', destination: 'bc1qaddr1...' },
        { amount: '250', destination: 'bc1qaddr2...' }
    ]
});
console.log(multi.actionString); // 'SEND|1|MYTOKEN|100|bc1qaddr1...|250|bc1qaddr2...'

// Full lifecycle: create, encode, sign, broadcast, wait for indexer
const tx = await sdk.submitAction(
    { action: 'SEND', params: { tick: 'MYTOKEN', amount: '100', destination: 'bc1q...' } },
    { pubkey: '02abc123...' },
    { wif: 'your-wif-key' }
);
console.log(tx.txid);    // transaction hash
console.log(tx.indexed); // action data from the indexer

// Wallet session: bind to a key and send multiple actions
const session = sdk.session('your-wif-key');
await session.send({ tick: 'MYTOKEN', amount: '50', destination: 'bc1q...' });
await session.send({ tick: 'MYTOKEN', amount: '50', destination: 'bc1q...' });
const balances = await session.getBalances();

// Workflow recipes: multi-step operations in one call
await sdk.issueAndDistribute('your-wif-key',
    { tick: 'NEWTOKEN', maxSupply: '1000000', decimals: 8 },
    [
        { destination: 'bc1qaddr1...', amount: '500000' },
        { destination: 'bc1qaddr2...', amount: '300000' }
    ]
);

// Query blockchain data
const token = await sdk.getToken('MYTOKEN');

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | NETWORK | Yes | (none) | Default coin and network (e.g. bitcoin-regtest, dogecoin-mainnet) | | SDK_API_PORT | No | 3005 | Port for the optional SDK helper API | | SDK_API_KEY | No | (none) | API key for the helper API; required as Authorization: Bearer <key> on every method except ping (methods reject with 401 when unset) | | CORS_ORIGIN | No | Disabled | CORS allowed origin for the helper API | | EXPLORER_URL / EXPLORER_PORT | No | 127.0.0.1 / 8080 | xchain-explorer location | | ENCODER_URL / ENCODER_PORT | No | 127.0.0.1 / 3003 | xchain-encoder location | | HUB_URL | No | (none) | Full xchain-hub URL | | HUB_API_HOST / HUB_PORT | No | (none) | xchain-hub host/port form used by some SDK paths | | HUB_API_KEY | No | (none) | API key for getallconfigs against keyed hubs; public zero-config discovery should use the hub's chain-registry endpoint instead | | WEBSOCKET_URL / WEBSOCKET_PORT | No | 127.0.0.1 / 3007 | Explorer WebSocket endpoint for live updates |

Scripts

| Command | Description | |---|---| | npm run api | Start JSON-RPC server (port from SDK_API_PORT, default 3005) | | npm test | Run unit tests | | npm run repl | Start interactive REPL with a pre-configured SDK instance | | npm run build | Production browser bundle -> dist/xchain_sdk.min.js | | npm run build:dev | Development browser bundle -> dist/xchain_sdk.js |

Test Suite

| Type | Tests | |---|---| | Unit: actions, validators, format selection, convenience methods, explorer, encoder, retry, WebSocket, wallet, auth, contracts, co-signer | 3206+ | | Integration: cross-module flows, VM/contract integration, hub discovery | 98+ | | Security: input attack surface, auth gates | 18+ | | Regression: curated critical-path suite, including round-trip serialize -> parse -> verify | 23+ | | Boundary: exact encoding limits | 35+ | | Fuzz: garbage types, unicode, prototype pollution | 65+ | | Chaos: malformed responses, HTTP errors, timeouts | 27+ | | Smoke: boot API server, end-to-end JSON-RPC | 9+ | | Performance | 3 | | Total | 3484+ |

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.