More details available in the BRFC Spec for merchant API.

Note: MAPI uses the JSON envelopes BRFC as well as the Fee Spec BRFC.

The REST API can also be seen in the Swagger UI.

For support and general discussion of both standards and reference implementations please join the following telegram group.

For development, you will only need GoLang installed in your environement.

MAPI configuration relies on a settings.conf file for the main service configurations as well as one or more fees*.json files (ex. fees.json for default fees, fees_low.json for lower fees, fees_user1.json for user1, etc.) to specify feesto be charged.

In order to sign responses, you will also need to run MinerId and provide the endpoint to MAPI in the settings configurations.

Open settings.conf and edit it with your settings:

• change httpAddress or httpsAddress to bind on specific interfaces

• change jwtKey for tokens Generate new JWT key:

  $ node -e "console.log(require('crypto').randomBytes(32).toString('hex'));"

• change quoteExpiryMinutes to set feeQuote expiry time

• change count of bitcoin nodes that merchant API is connected to as well as their respective Bitcoin RPC parameters:

  • bitcoin_count
  • bitcoin_1_host
  • bitcoin_1_port
  • bitcoin_1_username
  • bitcoin_1_password

• change minerId_URL and minerId_alias to set URL alias of minerId

Please see the Fee Spec BRFC for the fees JSON format.

$ ./run.sh

$ ./build.sh

Run individual tests or run all tests with:

$ go test ./...

You can find the public Docker Hub repository for mAPI here.

$ docker build . -t mapi_reference:1.1.0

Example configuration:

$ docker run -p 9004:9004 \
    -e httpAddress=:9004 \
    -e bitcoin_1_host=host.docker.internal \
    -e minerId_URL=http:https://host.docker.internal:9002/minerid \
    -e minerId_alias=testMiner \
    mapi_reference:1.1.0

Example running in daemon mode:

$ docker run -p 9004:9004 \
    -e httpAddress=:9004 \
    -e bitcoin_1_host=host.docker.internal \
    -e minerId_URL=http:https://host.docker.internal:9002/minerid \
    -e minerId_alias=testMiner \
    --restart=always \
    -d mapi_reference:1.1.0

The REST API has 4 endpoints:

GET /mapi/feeQuote

POST /mapi/tx

body:

{
  "rawtx": "[transaction_hex_string]"
}

GET /mapi/tx/{hash:[0-9a-fA-F]+}

POST /mapi/txs

body:

[
  {
    "rawtx": "[transaction_hex_string]"
  },
  {
    "rawtx": "[transaction_hex_string]"
  },
  {
    "rawtx": "[transaction_hex_string]"
  }
]

Merchant API providers would likely want to offer special or discounted rates to specific customers. To do this they would need to add an extra layer to enable authorization/authentication. An example implementation would be to use JSON Web Tokens (JWT) issued to specific users. The users would then include that token in their HTTP header and as a result recieve lower fee rates.

If no token is used and the call is done anonymously, then the default rate is supplied. If a JWT token (issued by the merchant API provider) is used, then the caller will receive the corresponding fee rate. At the moment, for this version of the merchant API implementation, the token must be issued and sent to the customer manually.

$ curl -H "Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOiIyMDIwLTEwLTE0VDExOjQ0OjA3LjEyOTAwOCswMTowMCIsIm5hbWUiOiJsb3cifQ.LV8kz02bwxZ21qgqCvmgWfbGZCtdSo9px47wQ3_6Zrk" localhost:9004/mapi/feeQuote

To create a token:

$ go run token_manager/main.go -days 100 -name "low"
Fee filename="fees_low.json"
Expiry=2020-10-14 11:44:07.129008 +0100 BST
Token = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOiIyMDIwLTEwLTE0VDExOjQ0OjA3LjEyOTAwOCswMTowMCIsIm5hbWUiOiJsb3cifQ.LV8kz02bwxZ21qgqCvmgWfbGZCtdSo9px47wQ3_6Zrk

Now anyone using this token will be offered the fees in the fees_low.json file.