Skip to content

SDK Reference

Soqucoin provides three SDKs at different maturity levels. The TypeScript SDK is the primary tool for browser-based development.

SDKs at a glance

SDK Language Status Use case
soqucoin-sdk Go ● Ready Full node integration, server-side signing, UTXO management
soq-lightning-sdk TypeScript Preview In-browser ML-DSA-44 signing, transaction building, Lightning (in progress)
soqushield_sdk Dart Alpha Mobile wallet primitives (SoquShield app)

TypeScript SDK (soq-lightning-sdk)

The browser-facing SDK. Generates ML-DSA-44 keypairs locally, builds and signs transactions client-side, and broadcasts via the public gateway. Keys never leave the browser.

Key generation

import { onchain } from "soq-lightning-sdk";

const { publicKey, secretKey } = onchain.mlDsaKeygen();
// publicKey: Uint8Array (1,312 bytes — ML-DSA-44 public key)
// secretKey: Uint8Array (2,560 bytes — ML-DSA-44 secret key)

Uses @noble/post-quantum (audited, pure-JS Dilithium implementation).

Address derivation

const address = onchain.deriveAddress(publicKey, "ssq");
// → "ssq1p..." (Bech32m, witness version 1)
// address = bech32m(hrp, 1, SHA256(pubkey₁₃₁₂))
Parameter Value
HRP (stagenet) ssq
Witness version 1
Hash SHA-256 of the 1,312-byte ML-DSA-44 public key
Encoding Bech32m (BIP-350)

Build, sign, and broadcast

const { rawTxHex, txid } = onchain.buildSignedSend({
  hrp: "ssq",
  utxos,                    // from GET /v1/address/{addr}/utxos
  recipientAddress,         // Bech32m destination
  amount,                   // in shors (1 SOQ = 100,000,000 shors)
  changeAddress: address,   // sender's own address
  senderPubkey: publicKey,  // 1,312-byte ML-DSA-44 pubkey
  senderSecret: secretKey,  // 2,560-byte ML-DSA-44 secret
  feeRate,                  // from GET /v1/feerate
});

// Broadcast
await fetch("https://gateway.soqu.org/v1/tx", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ rawtx: rawTxHex }),
});

The SDK assembles a witness-v1 transaction with the ML-DSA-44 signature inline. See Transaction format for the byte-level layout.

Public Gateway

The gateway at gateway.soqu.org provides read, faucet, and broadcast endpoints. It talks to soqucoind — you don't need to run a node.

Endpoints

Method Path Description
GET /v1/address/{address}/utxos List unspent outputs for an address
GET /v1/address/{address}/balance Address balance (confirmed + unconfirmed)
GET /v1/feerate Current recommended fee rate
GET /v1/tx/{txid}?verbose=1 Transaction details
GET /v1/block/{hash} Block details
GET /v1/info Node info (height, connections, version)
POST /v1/tx Broadcast a signed transaction ({ "rawtx": "..." })
POST /v1/faucet Request stagenet SOQ ({ "address": "..." })

CORS

The gateway allows requests from soqu.org, build.soqu.org, and localhost origins. For other origins, proxy through your own backend.

Rate limits

The faucet is rate-limited per address. API endpoints are not rate-limited during stagenet.

Go SDK (soqucoin-sdk)

Server-side SDK for full UTXO management, transaction construction, and node integration. Used by the gateway itself.

Next steps