spark-node-express

Spark Hackathon Node Server

Welcome to the Spark Hackathon!

Contained is a simple express server example written in plain javascript that calls most of our exposed sdk functions.

To get started:

yarn
yarn dev

or if you'd like you can copy this directory as a starting template for your own project and use a different package manager like npm:

npm install
npm run dev

To init a new wallet, make an empty POST request to either.

https://localhost:{PORT}/spark-wallet/init

or

https://localhost:{PORT}/issuer-wallet/init

Your mnemonic should then get saved to your local machine and you can explore our api from there.

To spin up a new wallet, delete the saved mnemonic files.

If your server crashes, remember to init your wallet again.

You can find more documentation for our sdks at https://docs.spark.info

Bitcoin Network configuration

To change the bitcoin network, update the BITCOIN_NETWORK variable in ./src/index.ts.

Postman Collection for testing:

You can import the below collection into postman to test the endpoints in dev. There are default values set in the body > raw of POST requests that you can easily edit.

Spark SDK API

Methods available to both spark and issuer wallets

As an IssuerSparkWallet extends the functionality of a SparkWallet, IssuerSparkWallets have access to all the methods available in a SparkWallet.

Get Wallet

Returns the raw wallet instance.

GET /spark-wallet/wallet
GET /issuer-wallet/wallet

Initialize Wallet

Initialize a new wallet or recovers an existing one.

POST /spark-wallet/wallet/init
POST /issuer-wallet/wallet/init

Request Body:

{
  mnemonicOrSeed?: string | undefined
}

If no mnemonic is provided, generates a new one and saves it.

Get Identity Public Key

Returns the wallet's identity public key.

GET /spark-wallet/wallet/identity-public-key
GET /issuer-wallet/wallet/identity-public-key

Get Spark Address

Returns the wallet's Spark address.

GET /spark-wallet/wallet/spark-address
GET /issuer-wallet/wallet/spark-address

Get Wallet Balance

Returns the current wallet balance, including token balances.

GET /spark-wallet/wallet/balance
GET /issuer-wallet/wallet/balance

Get Transfer History

Returns a list of transfers.

GET /spark-wallet/wallet/transfers?limit=20&offset=0
GET /issuer-wallet/wallet/transfers?limit=20&offset=0

Query Parameters:

• limit (optional Number): Number of transfers to return (default: 20)
• offset (optional Number): Offset for pagination (default: 0)

Get Pending Transfers

Returns a list of pending transfers.

GET /spark-wallet/wallet/pending-transfers
GET /issuer-wallet/wallet/pending-transfers

Claim Pending Transfers

Claim all pending transfers.

POST /spark-wallet/wallet/claim-transfers
POST /issuer-wallet/wallet/claim-transfers

Request Leaves Swap

Request a swap of leaves to optimize wallet structure.

POST /spark-wallet/wallet/request-leaves-swap
POST /issuer-wallet/wallet/request-leaves-swap

Request Body:

{
  targetAmount: number,
  leaves?: TreeNode[] | undefined
}

Send Spark Transfer

Send a Spark transfer to another address.

POST /spark-wallet/spark/send-transfer
POST /issuer-wallet/spark/send-transfer

Request Body:

{
  receiverSparkAddress: string,
  amountSats: number
}

Create Lightning Invoice

Generate a new Lightning Network invoice.

POST /spark-wallet/lightning/create-invoice
POST /issuer-wallet/lightning/create-invoice

Request Body:

{
  amountSats: number,
  memo?: string | undefined,
  expirySeconds?: number | undefined
}

Pay Lightning Invoice

Pay a Lightning Network invoice.

POST /spark-wallet/lightning/pay-invoice
POST /issuer-wallet/lightning/pay-invoice

Request Body:

{
  invoice: string
}

Get Lightning Receive Fee Estimate

Get a fee estimate for receiving Lightning payments.

GET /spark-wallet/lightning/receive-fee-estimate?amountSats=number
GET /issuer-wallet/lightning/receive-fee-estimate?amountSats=number

Query Parameters:

• amountSats (required Number): The amount to get the fee estimate for in satoshis

Get Lightning Send Fee Estimate

Get a fee estimate for sending Lightning payments.

GET /spark-wallet/lightning/send-fee-estimate?invoice=string
GET /issuer-wallet/lightning/send-fee-estimate?invoice=string

Query Parameters:

• invoice (required String): The encoded invoice to get the fee estimate for

Get Deposit Address

Generate a Bitcoin deposit address associated with the current wallet.

IMPORTANT: Deposits made to this address will NOT work for Token Announcements on L1.

GET /spark-wallet/on-chain/spark-deposit-address
GET /issuer-wallet/on-chain/spark-deposit-address

Get Unused Deposit Addresses

Returns a list of previously generated on chain deposit addresses associated with this Spark Wallet.

GET /spark-wallet/on-chain/unused-deposit-addresses
GET /issuer-wallet/on-chain/unused-deposit-addresses

Get Latest Deposit TxId

Returns the latest transaction ID deposited to the given Bitcoin address. This txid can be used to claim the deposit using /bitcoin/claim-deposit.

GET /spark-wallet/on-chain/latest-deposit-txid?btcAddress=string
GET /issuer-wallet/on-chain/latest-deposit-txid?btcAddress=string

Query Parameters:

• btcAddress (required String): The Bitcoin address to get the latest deposit transaction ID for

Claim Deposit

Claim a Bitcoin deposit.

POST /spark-wallet/on-chain/claim-deposit
POST /issuer-wallet/on-chain/claim-deposit

Request Body:

{
  txid: string
}

Withdraw to Bitcoin Address

Withdraw funds to a Bitcoin address.

POST /spark-wallet/on-chain/withdraw
POST /issuer-wallet/on-chain/withdraw

Request Body:

{
  onchainAddress: string,
  targetAmountSats?: number | undefined
}

Transfer Tokens

Transfer tokens to another address.

POST /spark-wallet/tokens/spark/transfer
POST /issuer-wallet/tokens/spark/transfer

Request Body:

{
  tokenPublicKey: string,
  tokenAmount: number,
  receiverSparkAddress: string
}

Get Token L1 Address

Returns the L1 address of the embedded LRC20 wallet. You MUST deposit to this address before announcing to L1.

IMPORTANT: The L1 address generated by the Spark Wallet from GET /bitcoin/deposit-address will NOT work for Token Announcements on L1.

GET /spark-wallet/tokens/on-chain/token-l1-address
GET /issuer-wallet/tokens/on-chain/token-l1-address

Withdraw Tokens

Withdraw tokens.

POST /spark-wallet/tokens/on-chain/withdraw
POST /issuer-wallet/tokens/on-chain/withdraw

Request Body:

{
  tokenPublicKey: string,
  tokenAmount: number
}

Issuer only methods

These endpoints are exclusively available for issuer wallets (/issuer-wallet/...).

Get Token Balance

Returns the issuer's token balance.

GET /issuer-wallet/tokens/token-balance

Get Token Public Key Info

Returns information about the token's public key.

GET /issuer-wallet/tokens/token-public-key-info

Get Token Activity

Returns a list of all token transactions.

GET /issuer-wallet/tokens/token-activity

Query Parameters:

• pageSize (optional Number): Number of transactions to return (default: 20)
• lastTransactionHash (optional String): The hash of the last transaction as a hex string
• layer (optional String): The layer of the last transaction "L1" or "SPARK"

Get Issuer Token Activity

Returns a list of all issuer token transactions.

GET /issuer-wallet/tokens/issuer-token-activity

Query Parameters:

• pageSize (optional Number): Number of transactions to return (default: 20)
• lastTransactionHash (optional String): The hash of the last transaction as a hex string
• layer (optional String): The layer of the last transaction "L1" or "SPARK"

Mint Tokens

Mint new tokens.

POST /issuer-wallet/tokens/spark/mint-tokens

Request Body:

{
  tokenAmount: string // Amount to mint (will be converted to BigInt)
}

Burn Tokens

Burn existing tokens.

POST /issuer-wallet/tokens/spark/burn-tokens

Request Body:

{
  tokenAmount: string // Amount to burn (will be converted to BigInt)
}

Freeze Tokens

Freeze tokens for a specific owner.

POST /issuer-wallet/tokens/spark/freeze-tokens

Request Body:

{
  ownerPublicKey: string
}

Unfreeze Tokens

Unfreeze tokens for a specific owner.

POST /issuer-wallet/tokens/spark/unfreeze-tokens

Request Body:

{
  ownerPublicKey: string
}

On-Chain Operations

IMPORTANT: Remeber you need UTXOs in your L1 address for L1 operations.

GET /issuer-wallet/tokens/on-chain/token-l1-address

Announce Token L1

Announce a new token on Layer 1.

POST /issuer-wallet/tokens/on-chain/announce-token

Request Body:

{
  tokenName: string,
  tokenTicker: string,
  decimals: number,
  maxSupply: number,
  isFreezable: boolean,
  feeRateSatsPerVb?: number | undefined
}

Mint Tokens L1

NOT YET IMPLEMENTED.

Mint tokens on Layer 1.

POST /issuer-wallet/tokens/on-chain/mint-tokens

Request Body:

{
  tokenAmount: number
}

Transfer Tokens L1

NOT YET IMPLEMENTED.

Transfer tokens on Layer 1.

POST /issuer-wallet/tokens/on-chain/transfer-tokens

Request Body:

{
  tokenAmount: number,
  receiverPublicKey: string
}