electrumrpc

README

Electrum JSON RPC Client

Note: The library does not have implementations of all Electrum RPC resources[WIP]. PRs for new resources and endpoints are welcome, or you can simply implement some yourself as-you-go.

Preposition

1. Install Electrum and create a wallet

2. Set RPC port

By default, it's random port - set it to any port you want

./run_electrum setconfig rpcport 7777

3. Set user and password for RPC

./run_electrum setconfig rpcuser user

./run_electrum setconfig rpcpassword password

4. Run Electrum as daemon

./run_electrum daemon start

If you want to start in testnet mode

./run_electrum --testnet daemon start

5. Load daemon wallet

./run_electrum daemon load_wallet

If daemon is running in testnet, you need to specify to load testnet wallet

./run_electrum --testnet daemon load_wallet

Now you have a local Electrum JSON RPC server running - congrats 🥳

If you need to stop it, use

./run_electrum daemon stop

or if running in testnet

./run_electrum --testnet daemon stop

Install

go get github.com/MarinX/electrumrpc

Use

import "github.com/MarinX/electrumrpc"

Example

You can find more in electrumrpc_test.go

// httpClient is optional
// if nil, the http.DefaultClient will be used
client := electrumrpc.New("<rpc-user>", "<rpc-password>", "<rpc-endpoint>", nil)

// Call RPC methods
ver, err := client.Version()
if err != nil {
	//handle error
	panic(err)
}
fmt.Println("Electrum version:", ver)

Not all endpoints are implemented right now. In those case, you can use Call method and point your model

var rpcResponse string
err := client.Call("version", nil, &rpcResponse)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println("Electrum version:", rpcResponse)

Available RPC methods

RPC Method	Available
version	✅
getaddressbalance	✅
getbalance	✅
validateaddress	✅
getservers	✅
createnewaddress	✅
getunusedaddress	✅
ismine	✅
gettransaction	✅
getseed	✅
listaddresses	✅
addrequest	✅
rmrequest	✅
clearrequests	✅
getrequest	✅
getfeerate	✅
signmessage	✅
verifymessage	✅

Contributing

PR's are welcome. Please read CONTRIBUTING.md for more info

License

MIT

Documentation

Index

• type Balance
• type Client
  • func New(username, password, addr string, httpClient *http.Client) *Client
  • func (c *Client) AddRequest(amount float64, memo string, expiration uint64) (res PaymentRequest, err error)
  • func (c *Client) Call(method string, params interface{}, result interface{}) error
  • func (c *Client) ClearRequests() (err error)
  • func (c *Client) CreateNewAddress() (res string, err error)
  • func (c *Client) GetAddressBalance(address string) (res Balance, err error)
  • func (c *Client) GetBalance() (res Balance, err error)
  • func (c *Client) GetFeeRate(feeMethod FeeMethod) (res uint64, err error)
  • func (c *Client) GetRequest(btcAddress string) (res PaymentRequest, err error)
  • func (c *Client) GetSeed(password string) (res string, err error)
  • func (c *Client) GetServers() (res map[string]Server, err error)
  • func (c *Client) GetTransaction(txid string) (res Transaction, err error)
  • func (c *Client) GetUnusedAddress() (res string, err error)
  • func (c *Client) IsMine(address string) (res bool, err error)
  • func (c *Client) ListAdddresses() (res []string, err error)
  • func (c *Client) ListRequest(pending, expired, paid bool) (res []PaymentRequest, err error)
  • func (c *Client) RemoveRequest(btcAddress string) (res bool, err error)
  • func (c *Client) SignMessage(btcAddress, message string) (res string, err error)
  • func (c *Client) ValidateAddress(address string) (res bool, err error)
  • func (c *Client) VerifyMessage(btcAddress, signature, message string) (res bool, err error)
  • func (c *Client) Version() (res string, err error)
• type FeeMethod
• type PaymentRequest
• type RequestError
  • func (r *RequestError) Error() string
• type Server
• type SignMessageRequest
• type Transaction
• type VerifyMessageRequest

Types

type Balance

type Balance struct {
	Confirmed   string `json:"confirmed"`
	Unconfirmed string `json:"unconfirmed"`
	Unmatured   string `json:"unmatured"`
	Lightning   string `json:"lightning"`
}

Balance model

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client holds the JSON RPC HTTP client with Basic Auth

func New

func New(username, password, addr string, httpClient *http.Client) *Client

New creates new client with username and password Optional, you can set your own http.Client If http.Client is not specified, the http.DefaultClient will be used

func (*Client) AddRequest

func (c *Client) AddRequest(amount float64, memo string, expiration uint64) (res PaymentRequest, err error)

AddRequest creates a payment request, using the first unused address of the wallet

func (*Client) Call

func (c *Client) Call(method string, params interface{}, result interface{}) error

Call is a method for calling JSON RPC endpoint Method is public - so if some func is missing, you can call here with your own model

func (*Client) ClearRequests

func (c *Client) ClearRequests() (err error)

ClearRequests removes all payment requests

func (*Client) CreateNewAddress

func (c *Client) CreateNewAddress() (res string, err error)

CreateNewAddress creates a new receiving address, beyond the gap limit of the wallet

func (*Client) GetAddressBalance

func (c *Client) GetAddressBalance(address string) (res Balance, err error)

GetAddressBalance returns balance for given address

func (*Client) GetBalance

func (c *Client) GetBalance() (res Balance, err error)

GetBalance return the balance of your wallet.

func (*Client) GetFeeRate

func (c *Client) GetFeeRate(feeMethod FeeMethod) (res uint64, err error)

GetFeeRate returns current suggested fee rate (in sat/kvByte), according to config settings or supplied parameters

func (*Client) GetRequest

func (c *Client) GetRequest(btcAddress string) (res PaymentRequest, err error)

GetRequest returns a payment request

func (*Client) GetSeed

func (c *Client) GetSeed(password string) (res string, err error)

GetSeed returns the generation seed of your wallet

func (*Client) GetServers

func (c *Client) GetServers() (res map[string]Server, err error)

GetServers returns the list of available servers

func (*Client) GetTransaction

func (c *Client) GetTransaction(txid string) (res Transaction, err error)

GetTransaction retrieve a transaction by id

func (*Client) GetUnusedAddress

func (c *Client) GetUnusedAddress() (res string, err error)

GetUnusedAddress returns the first unused address of the wallet, or None if all addresses are used An address is considered as used if it has received a transaction, or if it is used in a payment request.

func (*Client) IsMine

func (c *Client) IsMine(address string) (res bool, err error)

IsMine checks if address is in wallet. Return true if and only address is in wallet

func (*Client) ListAdddresses

func (c *Client) ListAdddresses() (res []string, err error)

ListAdddresses returns the list of all addresses in your wallet @TODO, support optional arguments to filter the results

func (*Client) ListRequest

func (c *Client) ListRequest(pending, expired, paid bool) (res []PaymentRequest, err error)

ListRequest lists the payment requests you made

func (*Client) RemoveRequest

func (c *Client) RemoveRequest(btcAddress string) (res bool, err error)

RemoveRequest removes a payment request Returns true if removal was successful

func (*Client) SignMessage

func (c *Client) SignMessage(btcAddress, message string) (res string, err error)

SignMessage signs a message with a key

func (*Client) ValidateAddress

func (c *Client) ValidateAddress(address string) (res bool, err error)

ValidateAddress check that an address is valid

func (*Client) VerifyMessage

func (c *Client) VerifyMessage(btcAddress, signature, message string) (res bool, err error)

VerifyMessage verifies a signature

func (*Client) Version

func (c *Client) Version() (res string, err error)

Version returns the version of Electrum.

type FeeMethod

type FeeMethod string

FeeMethod is fee estimation method

const (
	// FeeMethodNone is for none
	FeeMethodNone FeeMethod = ""
	// FeeMethodStatic is for static
	FeeMethodStatic FeeMethod = "static"
	// FeeMethodEta is for eta
	FeeMethodEta FeeMethod = "eta"
	// FeeMethodMempool is for mempool
	FeeMethodMempool FeeMethod = "mempool"
)

type PaymentRequest

type PaymentRequest struct {
	ID         string `json:"id"`
	Amount     uint64 `json:"amount"`
	Expiration uint64 `json:"exp"`
	Address    string `json:"address"`
	Memo       string `json:"memo"`
	URI        string `json:"URI"`
	Status     string `json:"status"`
	AmountBTC  string `json:"amount (BTC)"`
	Time       uint64 `json:"time"`
}

PaymentRequest is electrum payment request model

type RequestError

type RequestError struct {
	Id      uint64 `json:"code"`
	Message string `json:"message"`
}

func (*RequestError) Error

func (r *RequestError) Error() string

type Server

type Server struct {
	S       string `json:"s"`
	Pruning string `json:"pruning"`
	Version string `json:"version"`
}

Server is electrum server information

type SignMessageRequest

type SignMessageRequest struct {
	Address  string `json:"address"`
	Message  string `json:"message"`
	Password string `json:"password,omitempty"`
}

SignMessageRequest is model for signmessage method

type Transaction

type Transaction struct {
	Hex      string `json:"hex"`
	Complete bool   `json:"complete"`
	Final    bool   `json:"final"`
}

Transaction is bitcoin transaction model

type VerifyMessageRequest

type VerifyMessageRequest struct {
	Address   string `json:"address"`
	Signature string `json:"signature"`
	Message   string `json:"message"`
}

VerifyMessageRequest is model for verifymessage method