NAV
cURL

Intro

Why use the DotWallet for Developers APIs

DotWallet for Developers helps you use Bitcoin SV's blockchain infrastructure more easily.

With the DotWallet for Developers APIs, you can add powerful features to your app.

Apps integrating DotWallet login can be listed on the DotWallet App Store, bringing in tons of new user traffic.

Login

Create a simple and convenient login and sign up method for your users. DotWallet users can sign up for your app with one click, and non-DotWallet users can instantly sign up for DotWallet through Facebook, Google, WeChat, mobile number or email.

See Authorization and Get User Info for more.

Payments

Traditional apps can only accept payments from users but cannot send payments to users. With the DotWallet APIs, you can set up app-user or user-user transactions. You can easily set up advanced payment options like configuring multiple receivers and including transaction data in Bitcoin’s OP_RETURN field.

See Payments for more.

Automatic payments

After prompting the user once to authorize your app and transfer funds into the auto payments wallet, your app will not need the user to manually authorize every payment. Besides being convenient for users, this unlocks new possibilities for micro-transactions based applications and server-to-server use cases. Using DotWallet’s advanced networking technology, high volume micropayments using our API can break through the Bitcoin network’s limit on transactions.

See Automatic Payments for more.

Tokens and custom assets

Leverage DotWallet "Cards" to easily create digital assets that can be viewed, collected, and traded by DotWallet users right from the DotWallet app. If you'd like to make a 'Cards' compatible asset, we recommend creating it from the DotWallet Pro app UI. This will automatically list the asset in the marketplace. After listing, you can use our Badges APIs to handle transfers.

Create custom assets with Badges. Cards are simply tokens built on Badges. Cards have a specific set of attributes that make them more easily used in the DotWallet app. Create a Badge if you need more control over your tokenized asset.

Both Cards and Badges can be independently verified using Touchstone. If you are a wallet provider or exchange looking to support Badges, you can consider running a lightweight Touchstone node. See the github for details.

Blockchain data storage

Store your users’ data, or your app’s data in an immutable record on the blockchain, providing user confidence that their important data is backed up. This can be used to prove that certain data was created/received at a certain time and to verify the integrity and veracity of the data. This can be an auditable record that can for example prove the fairness of a prize payout’s conditions.

Data can be saved on-chain using the 'to' object of a payment order. In the 'type' field pass in 'script', then put your data in the 'content' field. You can attach data to user's payments, or set up your own DotWallet and pay for data saving yourself. For details, see Saving Data, Automatic Payments, and Payments.

Inspect the blockchain

As a large player in the Bitcoin mining industry, our Mempool mining pool lets us provide the most detailed and up to date information about the blockchain. Query transactions and blockchain data with our query APIs, and examine the state of Bitcoin mining with our direct connection to the Merchant API.

See Blockchain API for more.

Getting Started

This example uses our js library and Docker server from our SDK and tools section. For a more complete JavaScript example that does not use any libraries, please see the Pure JavaScript tutorial.

Find the complete code for this tutorial in our JavaScript Examples

Set up

<!--  Pull in the library. Make sure it loads after the body so it can find the
divs to attach to (defer) -->
<script
    src="https://unpkg.com/@dotwallet/js/dist/dotwallet.umd.js"
    defer
></script>
<!-- Our logic will go in this file. Make sure it loads after the @dotwallet/js library so we have access to the library -->
<script src="./index.js" defer></script>
<!-- set up divs for the library to attach to -->
<body>
    <div alt="dotwallet login button" id="my-login-button"></div>
    <div alt="dotwallet payment button" id="my-pay-button"></div>
</body>
// index.js

const DotWallet = dotwallet.default;
/** Check out server API documentation at
 * https://dotwallet-microservice-xfl2wlshtq-de.a.run.app/docs
 */
const SERVER_URL = 'https://dotwallet-microservice-xfl2wlshtq-de.a.run.app';
/** This is the client_id associated with the test server above. Replace with your own in a real app */
const authEndpoint = SERVER_URL + '/auth';
const clientID = '89d001043806644fdb4fb14099ff6be5';
/** Make sure to change to your own address! */
const receiveAddress = '1L4eTJidJjVajv4caJkmQyTFRXBnoN4Pap';
/** The current location, or another page. The redirect page must call DotWallet.loginRedirect() on page load */
const redirectURI = window.location.origin;

Login

// index.js
// ... continuing from above

DotWallet.loginButton('login-button', {
    clientID,
    redirectURI,
});

/**
 * Will also return the user's info.
 * In this example, we are just saving the server auth token, which we will need to make further calls to the backend */
DotWallet.loginRedirect({
    authEndpoint,
    successCallback: (userData) => {
        localStorage.setItem('server-token', userData.server_token);
    },
});

Payment orders

This will call our server to make an order_id, then use that to redirect the user to DotWallet's payment confirmation page.

// index.js
// ... continuing from above

const createOrderEndpoint = SERVER_URL + '/create-order';
const notifyURL = SERVER_URL + '/payment-result';

DotWallet.payButton('pay-button', {
    productName: 'Bananas',
    orderAmount: 900,
    receiveAddress,
    createOrderEndpoint,
    redirectURI,
    notifyURL,
    fetchHeaders: {
        Authorization: 'Bearer ' + localStorage.getItem('server-token'),
        'Content-type': 'application/json; charset=UTF-8',
    },
});

That's it! With three simple functions, you have implemented login authentication and payments in your app/webpage.

Schema

The following are the usage specifications of DotWallet open platform API resources. If you have any questions, please contact our official support.

Protocol

HTTP Request

HTTP Response

How to judge whether the HTTP request is successful?

Sucessful HTTP request example:

HTTP 200
{
    "code": 0,
    "msg": "",
    "data": {
        "access_token": "YOU-ACCESS-TOKEN",
        "expires_in": 7200,
        "token_type": "Bearer"
    }
}

In a successful request:

Authentication

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer YOUR-ACCESS-TOKEN"

If the access_token is invalid or expired, code will return a 75000 error

HTTP 200
{
  "code": 75000,
  "msg": "Invalid access token",
  "data": null
}

DotWallet will authenticate all Api resource requests. To authenticate simply add the following to each request's HTTP Header: Authorization: Bearer YOUR-ACCESS-TOKEN

How to get access_token in JWT form

Get application-level access_token

Get user-level access_token

Security

To ensure security, please do not disclose your client_id/client_secret. You should use the Server-to-Server method, that is, requests to the DotWallet authentication server to obtain access_tokens should be done from a secure server, not from a user client.

Rate Limits

Authorization

DotWallet for Developers' APIs require authorization before they can be used. For identity authorization, you need to register a developer account and create an application on our website.

Application Authorization

Application authorization, using OAuth2's Client Credentials authorization flow. See RFC6749 (https://tools.ietf.org/html/rfc6749#section-4.4)

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

Application authorization generally adheres to the standard OAuth2 Client Credentials authorization flow.

Application authorization is for developer application-level authorization to verify that requests are issued by applications registered with DotWallet for Developers.

curl -X POST 'https://api.ddpurse.com/v1/oauth2/get_access_token' \
-H 'Content-Type: application/json' \
--data-raw '{
    "client_id": "<YOUR-CLIENT-ID>",
    "grant_type": "client_credentials",
    "client_secret":"<YOUR-CLIENT-SECRET>"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "access_token": "JWT access token",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/oauth2/get_access_token

Request Body

Parameter Required Description
client_id YES Developer’s client_id
client_secret YES Developer’s client_secret
grant_type YES Fill in the fixed value: client_credentials

Response Body

Parameter Type Description
access_token string access_token for DotWallet API endpoints
expires_in int Expiration time of access_token (seconds)
token_type string Returns a fixed value: Bearer

How to use access_token

To use access_token for API endpoint authentication, please refer to Authentication

User Authorization

Our user authorization follows the standard authorization code flow of OAuth2. See RFC6749 for details (https://tools.ietf.org/html/rfc6749#section-4.1)

+----------+
| Resource |
|   Owner  |
|          |
+----------+
     ^
     |
    (B)
+----|-----+          Client Identifier      +---------------+
|         -+----(A)-- & Redirection URI ---->|               |
|  User-   |                                 | Authorization |
|  Agent  -+----(B)-- User authenticates --->|     Server    |
|          |                                 |               |
|         -+----(C)-- Authorization Code ---<|               |
+-|----|---+                                 +---------------+
  |    |                                         ^      v
 (A)  (C)                                        |      |
  |    |                                         |      |
  ^    v                                         |      |
+---------+                                      |      |
|         |>---(D)-- Authorization Code ---------'      |
|  Client |          & Redirection URI                  |
|         |                                             |
|         |<---(E)----- Access Token -------------------'
+---------+       (w/ Optional Refresh Token)

User authorization is based on Oauth2's Authorization Code grant, allowing third-party applications to safely access certain capabilities authorized by DotWallet users.

Use cases: This token is used for the following cases and API endpoints.

Authorization Code grant flow:

Step 1: Construct URI

Example URI: https://api.ddpurse.com/v1/oauth2/authorize?client_id=YOUR-CLIENT-ID&redirect_uri=http%3A%2F%2FYOUR-REDIRECT-URL&response_type=code&state=YOUR-STATE&scope=user.info

URL Parameters

Parameter Required Description
client_id YES Developer’s client_id
redirect_uri YES The redirect URL after authorization. Needs to be url_encoded
response_type YES Fill in the fixed value : code
state YES It is recommended to use a random string of more than 32 bits (such as UUID). The state is used to verify the consistency of the request and callback. This can prevent csrf attacks.
scope YES Authorization scope. The list of permissions that the user agrees to authorize. These permissions are required for certain API endpoints. Needs to be url_encoded. Use spaces to separate multiple permissions. For a list of currently supported scope permissions, please check the scope list below

scope list

scope Description
user.info Get user's basic information
autopay.bsv BSV automatic payments permission. If activated you can make payments and deductions on the user's behalf.
autopay.btc BTC automatic payments permission. If activated you can make payments and deductions on the user's behalf.
autopay.eth ETH automatic payments permission. If activated you can make payments and deductions on the user's behalf.

Step 2: Redirect the user to the URI constructed in step 1

For example, you can use a simple <a> to redirect the user to DotWallet's login authorization page.

<a href="https://api.ddpurse.com/authorize?client_id=YOUR-CLIENT-ID&redirect_uri=http://localhost:9094/oauth2&response_type=code&state=xxx&scope=user.info">Use DotWallet Login</a>

Step 3: Receive the code through the callback uri

The authorization server will be redirect the application client to the provided callback address, appending the following parameters:

# The auth server will redirect to your callback url with these query parameters
curl -L https://YOUR-HOST/YOUR-REDIRECT-URI?code=xxxxx&state=YOUR-STATE-VALUE

Response URL Parameters

Parameter Required Description
state YES It is recommended to use a random string of more than 32 bits (such as UUID). The state is used to maintain the state of the request and callback, and bring it back to the third party as it is after the authorization request. This parameter can be used to prevent csrf attacks
code YES The code generated by the authorization server in exchange for access_token

Step 4: Exchange code for access_token

curl -X POST 'https://api.ddpurse.com/v1/oauth2/get_access_token' \
-H 'Content-Type: application/json' \
--data '{
    "client_id": "<YOUR-CLIENT-ID>",
    "client_secret": "<YOUR-CLIENT-SECRET>",
    "grant_type": "authorization_code",
    "code": "<YOUR-AUTHORIZATION-CODE>",
    "redirect_uri":"https://your_callback_url"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "access_token": "JWT access token",
    "expires_in": 7200,
    "refresh_token": "PDIWLOLXXQM5KAWINUFP7G",
    "scope": "user.info autopay.bsv autopay.eth",
    "token_type": "Bearer"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/oauth2/get_access_token

URL Parameters

Parameter Required Description
client_id YES Developer’s client_id
client_secret YES Developer’s client_secret
redirect_uri YES The redirect_uri here must be the same as the first step. Note: This will not be used to do a browser redirect, it is just used to authenticate that the call is made from the same source as the first step
grant_type YES Fill in the fixed value : authorization_code
code YES The code obtained in step 3

Response Body

Parameter Type Description
access_token string access_token used to access the API interface
expires_in int Expiration time of access_token (seconds)
refresh_token string The validity period of refresh_token is 7 days by default. When the access_token expires, you can get the access_token again through refresh_token
scope string List of scope permissions authorized by the user
token_type string Returns a fixed value: Bearer

Step 5: Refresh access_token with refresh_token (optional)

curl -X POST 'https://api.ddpurse.com/v1/oauth2/get_access_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "YOUR-CLIENT-ID",
    "client_secret": "YOUR-CLIENT-SECRET",
    "grant_type": "refresh_token",
    "refresh_token":"LUWNYMQ0WG69LLYN--SMIG"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "access_token": "JWT access token",
    "expires_in": 7200,
    "refresh_token": "PDIWLOLXXQM5KAWINUFP7G",
    "scope": "user.info autopay.bsv autopay.eth",
    "token_type": "Bearer"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/oauth2/get_access_token

Request Body

Parameter Required Description
client_id YES Developer’s client_id
client_secret YES Developer’s client_secret
grant_type YES Fill in the fixed value: refresh_token
refresh_token YES refresh_token value obtained in step 4

Response Body

Parameter Type Description
access_token string access_token used to access DotWallet API endpoints
expires_in int Expiration time of access_token (seconds)
refresh_token string The validity period of refresh_token is 7 days by default. When the access_token expires, you can get the access_token again through refresh_token
scope string List of scope permissions authorized by the user
token_type string Returns a fixed value: Bearer

How to use access_token

To use access_token for API endpoint authentication, please refer to Authentication

Signature Authentication

If you can prove that you own the private key belonging to a DotWallet wallet, you can perform actions on that wallet's behalf. This removes the need to apply for and manage auth tokens like in the previous two authentication methods.

This is often more convenient for developers who want to perform an action from their own account. It also opens up the DotWallet's APIs to be used by DotWallet users who have some some coding ability.

This authentication method is especially used with the Badge API.

Usage example

/* JavaScript */
//npm install bitcore-mnemonic 
// (this example used bitcore-mnemonic version 8.24.1)
//npm install bsv 
// (this example used bsv version 2.0.3)
const Mnemonic = require('bitcore-mnemonic');
const bsv = require('bsv')

// words=seed phrase exported from DotWallet account
const words = 'able chase soccer vocal kid car motor absurd test glass firm quick'
const code = new Mnemonic(words);
const xpri = code.toHDPrivateKey()
const xp = xpri.deriveChild("m/44'/0'/0'/0/0")
// generate private key
const privateKey = bsv.PrivKey.fromBn(xp.privateKey.toBigNumber())
// generate public key
const publicKey = bsv.PubKey.fromPrivKey(privateKey)
console.log("Base58 privKey:", bsv.Base58.encode(privateKey.toBuffer()));
console.log("Hex encoded pubKey:", publicKey.toHex());

//1、Pass in payload data. In a real use case change this to real payload data:
const data = {
  col1: "1",
  col2: 2
};
//2、Make the payload a json string
const jsonStr = JSON.stringify(data);

//3、Hash the payload string
const hashStr = bsv.Hash.sha256(Buffer.from(jsonStr));

//4、Sign the payload string with private key
const signature = bsv.Ecdsa.sign(hashStr, bsv.KeyPair.fromPrivKey(privateKey));

// Prepare DotWallet API request
const reqParams = {
  payload: jsonStr,
  signature: signature.toHex(),
  pubkey: publicKey.toHex()
};
console.log("request body:", JSON.stringify(reqParams));

/* You should get this result running the above code */
//Base58 privKey:3tro9DeCRC6R2uoFhMEpZ6GxuCwqgcRuF79YyiVAzov8XXN
//Hex encoded pubKey: 02d126757e947016f9014cdab666fc47b8031bb3cdb47401d68182333ac2b489f5
//request body: {"payload":"{\"color\":\"black\",\"age\":15}","signature":"3044022023c1a7230e55215d9156f82a9e911ff1cd04a8ae0577539388bdada19fd2010a0220169e04cd1123b61f5c4825c2c73ead3251df13dd7a960b56429030090deab414","pubkey":"02d126757e947016f9014cdab666fc47b8031bb3cdb47401d68182333ac2b489f5"}

How to get a public/private key pair

To use this API you must have the private/public keys from a DotWallet user account wallet. Sign up for a wallet on our web app (mobile app is not supported). Go to settings > Wallet Backup and export your seed phrase. Then use the seed phrase to recreate the public/private keys. Please see the example for how to do that.

Public/private key algorithm description

IMPORTANT

Please carefully manage your private key. The private key can access and control all of the assets in the wallet. Leaking your private key could result in the loss of your assets.

Usage example

Generate private and public keys from seed phrase, then use private key to sign payload. Please see the example code.

-Signature: The process by which the sender uses their private key to sign some data. -Signature verification: The process by which the sign-verifier (in this case DotWallet's server) uses the public key to verify the message.

JavaScript

JS library

bsv 2.0.3

Install

npm install bsv

API Reference

The following are detailed documentation for all of the currently available API endpoints provided by DotWallet for Developers.

User Info

Get User Info

Through the user information API endpoint, third-party applications can obtain information authorized by DotWallet users.

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/user/get_user_info' \
-H "Authorization: Bearer <USER-ACCESS-TOKEN>"

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "id": "1278104675169476608",
    "nickname": "hello world",
    "avatar": "https://your_avatar"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/user/get_user_info

Request Header

Parameter Type Required Description
Authorization string Yes Authorization: Bearer USER-ACCESS-TOKEN,Grant Type: User Authorization

Response Body

Parameter Type Description
id string User ID
nickname string User nickanme
avatar string User avatar

Get User Receive Address

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/user/get_user_receive_address' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "coin_type":"BTC",
    "user_id":"USER-ID"
}'

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "autopay_wallet": {
            "wallet_index": 0,
            "coin_type": "BSV",
            "address": "mu66m5zsDKQRPioi3KE6YagcJwFVqJAbcr",
            "paymail": "y1Qzj7@localhost:9871"
        },
        "primary_wallet": {
            "wallet_index": 0,
            "coin_type": "BSV",
            "address": "mjSsxjLKvqhixNL6h9NkWbx7K3PwGoUPXZ",
            "paymail": "7rE8vS@localhost:9871"
        }
    }
}

HTTP Request

POST https://api.ddpurse.com/v1/user/get_user_receive_address

Request Header

Param Type Required Description
Authorization string Yes Authorization: Bearer APP-ACCESS-TOKEN,auth method: Application Auth

Request Body

Param Type Required Description
user_id string Yes User ID
coin_type string Yes Coin type. Currently supported: BTC, BSV, ETH

Response Body

Param Type Description
+primary_wallet object Primary User Wallet
└ address string address
└ paymail string paymail address, only support BSV
└ coin_type string coin type
└ wallet_index string Wallet index, 0 for WEB wallet, other for PRO wallet
+autopay_wallet object Autopay User Wallet
└ address string address
└ paymail string Paymail address, only support BSV
└ coin_type string Coin type
└ wallet_index string Wallet index, fixed value 0

Get User Badge Balance

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/user/get_badge_balance' \
--header 'Authorization: Bearer <USER-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "badge_code": "<BADGE-CODE>"
}'

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "confirm": 0,
        "unconfirm": 98998000,
        "wallet_index": 0,
    }
}

HTTP Request

POST https://api.ddpurse.com/v1/user/get_badge_balance

Request Header

Param Type Required Description
Authorization string Yes Authorization: Bearer USER-ACCESS-TOKEN,Grant Type: User Authorization

Request Payload

Param Type Required Description
badge_code string Yes badge code

Response Body

Param Type Description
confirm int Confirmed balance
unconfirm int Unconfirmed balance
wallet_index int Wallet index, 0 for WEB wallet, other for PRO wallet

Transactions

With DotWallet for Developers payment APIs, third parties can quickly integrate powerful payment functions.

When paying, you will guide DotWallet users to log in to the dot wallet application (web app) to complete the transaction.

Single payment orders require the user to manually confirm the each transaction. With Automatic Payments, the user only needs to authorize once and the application can initiate transactions on their behalf.

Single Payment Order

Step 1: Create a Payment Order

# With shell, you can just pass the correct header with each request

curl --location --request POST 'https://api.ddpurse.com/v1/transact/order/create' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "out_order_id":"0001",
    "coin_type":"BSV",
    "to":[{
        "type":"address",
        "content":"mnjV6Fy9ge35xWsqu9rSS4bTG2wxsuoKy7",
        "amount":10000000
    },
    {
        "type":"script",
        "content":"006a",
        "amount":0
     }
    ],
    "product":{
        "id":"001",
        "name":"apple",
        "detail":"This is a red apple."
    },
    "subject":"Red Apple",
    "notify_url":"https://test.com",
    "redirect_uri":"https://test.com",
    "expires":2601452710
}'

HTTP Request

POST https://api.ddpurse.com/v1/transact/order/create

Request Header

Param Type Required Description
Authorization string YES Authorization: Bearer APP-ACCESS-TOKEN,auth method: Application Auth

Request Body

Param Type Required Description
out_order_id string YES Client defined order number. Recommend 32 digit random UUID string
coin_type string YES Payment coin type. Currently supported: BTC, BSV, ETH
+to object[] YES An array of transaction objects.
└ type string YES Receiver type, please check the receiver type below.
└ content string YES Receiver content, please check the receiver content below.
└ amount int YES Transaction amount. Unit: satoshi (BSV, BTC) or gwei (ETH). Minimum amount: 546 satoshi (BSV, BTC) for address transactions. script and ETH transactions have no minimum.
+product object YES Product information object
└ id string YES Product ID/SN
└ name string YES Product name
└ detail string NO Product description
badge_code string NO Badge code. Including this code marks this transaction as a Badges transaction
subject string NO Order label or description
notify_url string MAYBE Address to send payment result notification to. Each request must include either notify_url or redirect_uri.
redirect_uri string MAYBE Address to redirect browser to after payment completion. Each request must include either notify_url or redirect_uri.
expires int NO Order expiry time. Unix epoch time in seconds. Leave this blank or submit 0 and the order will not expire

Receive Type

type content
address should be a valid address
script should be a hex script
paymail should be a paymail address
user_primary_web should be DotWallet User ID

Response Body

{
  "code": 0,
  "msg": "",
  "data": "1318817847320780800"
}
Param Type Description
data string Order ID (order_id)

Step 2:Construct payment URL, redirect user

To redirect the user you can make a simple <a>tag element

<a href="https://api.ddpurse.com/v1/transact/order/apply_payment?order_id=<YOUR-ORDER-ID>">Pay with DotWallet</a>

https://api.ddpurse.com/v1/transact/order/apply_payment?order_id={YOUR-ORDER-ID}

Authorize

The user will be redirected to the payment page of the DotWallet web app after clicking the link. It may require the user to log in, and then perform the payment operation.

Step3:Receive payment result

After the user completes the payment you can be notified of the payment result. The result is sent in JSON format with a POST request to your provided notify_url.

Notify Request Body

To verify that the payment result notification came from DotWallet servers, we have added a signature to the response using our official public key.

Example payment result notification:

{
  "signature": "3045022100ae6ab3f9d45e24cc03b5db5e82cfc16df893e6e49914755673b365c8342342ad022015ba247646cd16e75986d802405ad869bb3dec56233562cc483f3fa05dc4e187",
  "pubkey": "03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33",
  "payload": "{\"order_id\":\"1354638810134093824\",\"out_order_id\":\"1077\",\"user_id\":\"b940725f2fb97534122613a9683015c6\",\"amount\":1111,\"fee\":272,\"txid\":\"7a26ac299829509cd4503682eef7d68ffd7022d39c1b814e072ce980a5be8c38\",\"badge_code\":\"e412fe75527b9251ede97d84b17037cd2524698bd68b9561df3d4ab221515c6d\"}"
}

Signature verification example

//JavaScript Demo
//npm install bsv
//bsv version:2.0.4
const bsv = require("bsv");

let payload = `{"order_id":"1354638810134093824","out_order_id":"1077","user_id":"b940725f2fb97534122613a9683015c6","amount":1111,"fee":272,"txid":"7a26ac299829509cd4503682eef7d68ffd7022d39c1b814e072ce980a5be8c38","badge_code":"e412fe75527b9251ede97d84b17037cd2524698bd68b9561df3d4ab221515c6d"}`;
let signatureHex = `3045022100ae6ab3f9d45e24cc03b5db5e82cfc16df893e6e49914755673b365c8342342ad022015ba247646cd16e75986d802405ad869bb3dec56233562cc483f3fa05dc4e187`;
let pubkeyHex = `03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33`;

let hash = bsv.Hash.sha256(Buffer.from(payload, "utf8"));
let pubkey = bsv.PubKey.fromBuffer(Buffer.from(pubkeyHex, "hex"));
let sig = bsv.Sig.fromBuffer(Buffer.from(signatureHex, "hex"));
let verify = bsv.Ecdsa.verify(hash, sig, pubkey);
//true==success false==failure
console.log(verify);
//Java Demo
//gradle dependencies: compile group: 'org.bitcoinj', name: 'bitcoinj-core', version: '0.14.7'
import com.subgraph.orchid.encoders.Hex;
import org.bitcoinj.core.ECKey;
import org.bitcoinj.core.Sha256Hash;

public class Demo {
    public static void main(String[] args) {
            String payload = "{\"order_id\":\"1354638810134093824\",\"out_order_id\":\"1077\",\"user_id\":\"b940725f2fb97534122613a9683015c6\",\"amount\":1111,\"fee\":272,\"txid\":\"7a26ac299829509cd4503682eef7d68ffd7022d39c1b814e072ce980a5be8c38\",\"badge_code\":\"e412fe75527b9251ede97d84b17037cd2524698bd68b9561df3d4ab221515c6d\"}";
            String signatureHex = "3045022100ae6ab3f9d45e24cc03b5db5e82cfc16df893e6e49914755673b365c8342342ad022015ba247646cd16e75986d802405ad869bb3dec56233562cc483f3fa05dc4e187";
            String pubkeyHex = "03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33";
            ECKey.ECDSASignature sig = ECKey.ECDSASignature.decodeFromDER(Hex.decode(signatureHex));
            ECKey pubkey = ECKey.fromPublicOnly(Hex.decode(pubkeyHex));
            Sha256Hash payloadHash = Sha256Hash.of(payload.getBytes());
            boolean result = pubkey.verify(payloadHash,sig);
            System.out.println(result);
    }
}
Param Type Description
payload json string Notification data, see:Payload below for details
signature string The signed notification data. See js example
pubkey string DotWallet for Developers' official public key. Make sure it is 03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33

Payload

Param Type Description
order_id string Order ID
out_order_id string Client defined order ID
user_id string User ID of the payer
amount int Payment amount. Unit: satoshi(BSV, BTC) or gwei (ETH)
fee int miner fee. Unit: satoshi(BSV, BTC) or gwei (ETH)
txid string Transaction ID

Query Order Status

# With shell, you can just pass the correct header with each request
curl --location --request GET 'https://api.ddpurse.com/v1/transact/order/get_order' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id":"1306515412057333760"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "amount": 200000,
    "coin_type": "BSV",
    "created_at": 1604997798,
    "order_id": "1326082996066852864",
    "out_order_id": "0003",
    "payer_user_id": "6a1b2161094e32bf2c352910218048da",
    "product_detail": "This is a red apple.",
    "product_id": "001",
    "product_name": "apple",
    "status": 2,
    "subject": "Red Apple",
    "transaction": {
      "blockhash": "",
      "blockheight": -1,
      "confirmation": -1,
      "fee": 116,
      "time": 1605254849,
      "vins": [
        {
          "address": "mqcsXSYXd1fimNKWZS7tyPFyunA1ewzVhV",
          "amount": 9881906,
          "index": 0
        }
      ],
      "vouts": [
        {
          "address": "mjLxBnPyFPP1qTDzu7Lhv597gJGR5kpPvd",
          "amount": 200000,
          "index": 0
        },
        {
          "address": "n2V8gRt1ytG8QGaA9VqH7JnSLvNcU2pGW6",
          "amount": 9681790,
          "index": 1
        }
      ]
    },
    "txid": "0e3cfcf80b08c3ecde8b500f7fd336143e313a74a88d11a6bf7e2e0b051e4611"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/transact/order/get_order

Request Header

Param Type Required Description
Authorization string YES Authorization: Bearer APP-ACCESS-TOKEN,auth method: Application Auth

Request Body

Param Type Required Description
order_id string Order ID

Response Body

Param Type Description
order_id string Order ID
out_order_id string Client provided order ID 号
payer_user_id string User ID of the payer
coin_type string Payment coin type. Currently supported: BTC, BSV, ETH
amount int Payment amount. Unit: satoshi (BSV, BTC) or gwei (ETH)
fee int Miner fee. Unit: satoshi (BSV, BTC) or gwei (ETH)
txid string Transaction ID
subject string Order label or description
product_id string Product ID/SN
product_name string Product name
product_detail string Product description
confirmation int Transaction confirmations. -1 means it has not yet been put on the blockchain
status int Order status 1 means not paid. 2 means paid
created_at int Order creation time. Unix epoch time in seconds
+transaction object Transaction details(only available for completed payments)
└ blockhash string Transaction hash (txid)
└ blockheight int Transaction block height. -1 means not yet included in a block
└ time int Time that transaction was included in a block. Unix epoch time in seconds
└ confirmation int Confirmations. -1 means not yet included in a block
└ fee int Transaction miner fee
└ txid string Transaction ID
└ +vins object[] Transaction inputs
└ └ address string Address
└ └ amount string Amount
└ └ index string Vins order index
└ +vouts object[] Transaction outputs
└ └ address string Address
└ └ amount string Amount
└ └ index string Vouts order index

Automatic Payment

Automatic payment allows apps that have received User authorization to make automatic payments on behalf of a DotWallet user. The user will only need to be prompted once, after which the app can make payments with the users funds up to the wallet balance.

Use cases

It is suitable for high frequency payments and to avoid users having to jump to the payment confirmation page all the time. This is useful in lotteries, repeated payments, games, and social media, or for allowing third-party applications to pay utility bills on behalf of the user.

Automatic payment flow

Automatic Payment API Endpoint

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/transact/order/autopay' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "out_order_id":"0001",
    "coin_type":"BSV",
    "user_id":"6a1b2161094e32bf2c35298048da",
    "to":[{
        "type":"address",
        "content":"mnjV6Fy9ge35xWsqu9rSS4bTG2wxsuoKy7",
        "amount":10000
    },
    {
        "type":"script",
        "content":"006a",
        "amount":0
     }],
    "product":{
        "id":"001",
        "name":"apple",
        "detail":"This is a red apple."
    },
    "subject":"Red Apple",
    "notify_url":"https://www.ddpurse.com/"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "order_id": "1318822791176265728",
    "out_order_id": "0001",
    "user_id": "6a1b2161094e32bf2c3218048da",
    "amount": 10000,
    "fee": 233,
    "txid": "6d99b1f014ac1e22ed5977b5191883c098e820476283bbad438ffcf95c5663f9",
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/transact/order/autopay

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Parameter Type Required Description
out_order_id string YES Client defined order number. Recommend 32 digit random UUID string
coin_type string YES Payment coin type. Currently supported: BTC, BSV, ETH
user_id string YES DotWallet User ID
+to object[] YES An array of transaction objects.
└ type string YES Receiver type, please check the receiver type below.
└ content string YES Receiver content, please check the receiver content below.
└ amount int YES Transaction amount. Unit: satoshi (BSV, BTC) or gwei (ETH). Minimum amount: 546 satoshi (BSV, BTC) for address transactions. script and ETH transactions have no minimum.
+product object YES Product information object
└ id string YES Product ID/SN
└ name string YES Product name
└ detail string NO Product description
subject string NO Order label or description
notify_url string NO Address to send payment result notification to

Receive Type

type content
address should be a valid address
script should be a hex script
paymail should be a paymail address
user_primary_web should be DotWallet User ID

Response Body

Param Type Description
order_id string Order ID
out_order_id string Client defined order ID
user_id string User ID of the payer
amount int Payment amount. Unit: satoshi(BSV, BTC) or gwei (ETH)
fee int miner fee. Unit: satoshi(BSV, BTC) or gwei (ETH)
txid string Transaction ID

After the user completes the payment, the payment result info will be to sent in JSON format to notify_url in a POST request.

Notify Request Body

To verify that the payment result notification came from DotWallet servers, we have added a signature to the response using our official public key.

Example payment result notification:

{
  "signature": "3045022100ae6ab3f9d45e24cc03b5db5e82cfc16df893e6e49914755673b365c8342342ad022015ba247646cd16e75986d802405ad869bb3dec56233562cc483f3fa05dc4e187",
  "pubkey": "03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33",
  "payload": "{\"order_id\":\"1354638810134093824\",\"out_order_id\":\"1077\",\"user_id\":\"b940725f2fb97534122613a9683015c6\",\"amount\":1111,\"fee\":272,\"txid\":\"7a26ac299829509cd4503682eef7d68ffd7022d39c1b814e072ce980a5be8c38\",\"badge_code\":\"e412fe75527b9251ede97d84b17037cd2524698bd68b9561df3d4ab221515c6d\"}"
}

Signature verification example

//npm install bsv
//bsv version:2.0.4
const bsv = require('bsv')

let payload = `{"order_id":"1354638810134093824","out_order_id":"1077","user_id":"b940725f2fb97534122613a9683015c6","amount":1111,"fee":272,"txid":"7a26ac299829509cd4503682eef7d68ffd7022d39c1b814e072ce980a5be8c38","badge_code":"e412fe75527b9251ede97d84b17037cd2524698bd68b9561df3d4ab221515c6d"}`
let signatureHex = `3045022100ae6ab3f9d45e24cc03b5db5e82cfc16df893e6e49914755673b365c8342342ad022015ba247646cd16e75986d802405ad869bb3dec56233562cc483f3fa05dc4e187`
let pubkeyHex = `03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33`

let hash = bsv.Hash.sha256(Buffer.from(payload,'utf8'))
let pubkey = bsv.PubKey.fromBuffer(Buffer.from(pubkeyHex,'hex'))
let sig = bsv.Sig.fromBuffer(Buffer.from(signatureHex,"hex"))
let verify = bsv.Ecdsa.verify(hash,sig,pubkey)
//true==success false==failure
console.log(verify);
Param Type Description
payload json string Notification data, see:Payload below for details
signature string The signed notification data. See js example
pubkey string DotWallet for Developers' official public key. Make sure it is 03bf122b0f479faffecd165cae37b0441b9e3ca6f85edc43a870973c61f1375d33

Payload

Param Type Description
order_id string Order ID
out_order_id string Client defined order ID
user_id string User ID of the payer
amount int Payment amount. Unit: satoshi(BSV, BTC) or gwei (ETH)
fee int miner fee. Unit: satoshi(BSV, BTC) or gwei (ETH)
txid string Transaction ID

After the transaction is completed, DotWallet will send up to 15 notifications within the next 24 hours. After you have successfully received a notification, please respond to the POST request with the following info to confirm you've received the notification and cancel the subsequent notifications.

Notify Response Body

Parameter Type Description
code int status code,0:success

Example response:

{
  "code": 0,
}

Handle insufficient balance and transaction limit too low

If the payment request from the previous step returns an error with the code 10180007 then the user's autopay wallet balance is too low. A code of 10180029 means the user's designated transaction limit is too low. In these cases you should redirect the user to change the settings or move funds into their autopay wallet.

10180007 Redirect the user to this URL:

https://api.ddpurse.com/v1/user/autopay_transfer?redirect_url=<YOUR_REDIRECT_URL>

10180029 Redirect the user to this URL:

https://api.ddpurse.com/v1/user/autopay_config?client_id=<YOUR_CLIENT_ID>

URL Parameters

Parameter Required Description
redirect_url NO The redirect URL after authorization. Needs to be url_encoded
client_id YES Developer’s client_id

Query user's automatic payment wallet balance

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/user/get_autopay_balance' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "coin_type": "BSV",
    "user_id": "6a1b2161094e32bf2c352910218048da"
}'

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "confirm": 85613,
        "unconfirm": 0
    }
}

HTTP Request

POST https://api.ddpurse.com/v1/user/get_autopay_balance

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Parameter Type Required Description
coin_type string YES The currency to be queried, supports BTC, BSV, ETH
user_id string YES User ID to be queried

Response Body

参数名 类型 说明
confirm int Confirmed balance
unconfirm int Unconfirmed balance

Save Data On Chain or Run Scripts

Save data or a script onto the blockchain by using the Payment Order API or the Automatic Payment API. Please see the links for how to use these APIs.

https://api.ddpurse.com/v1/transact/order/autopay or https://api.ddpurse.com/v1/transact/order/create

In the to parameter object array, pass in script for type, and pass in the data for content.

Use cases

This can be used to verify or store various records and data. Saving data on chain can be used to improve the longevity of data. It can be used along with timestamps to prove that a certain data transaction happened at a certain time. For large data sets, it is sometimes better to just save a hash of the data on chain. The hash can be later be compared to the data to verify that the data has not been modified.

Data/script Format

Make sure your data/script is a hex encoded string. Prefix the data with 006a

# Saving data with automatic payment:
curl --location --request POST 'https://api.ddpurse.com/v1/transact/order/autopay' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "out_order_id":"0001",
    "coin_type":"BSV",
    "user_id":"6a1b2161094e32bf2c35298048da",
    "to":[{
        "type":"script",
        "content":"006a<YOUR HEX ENCODED DATA HERE>",
        "amount":0
    }],
    "product":{
        "id":"001",
        "name":"data",
        "detail":"This is some important data."
    },
    "notify_url":"https://www.example.com/"
}'
// Saving data with automatic payment:
async function saveDataWithAutopayment(DATA, YOUR_APP_ACCESS_TOKEN) {
  const hexEncoded = Buffer.from(JSON.stringify(DATA), 'utf8').toString('hex');
  const orderData = {
    user_id: '',
    out_order_id: uuidv4(),
    coin_type: 'BSV',
    to: [
      {
        type: 'script',
        content: `006a${hexEncoded}`,
        amount: 0,
      },
    ],
    product: {
      id: uuidv4(),
    },    
    notify_url:'https://www.example.com/'
  };
  const options = {
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${YOUR_APP_ACCESS_TOKEN}`,
    },
    method: 'POST',
    data: orderData,
  };
  const response = await axios(`https://api.ddpurse.com/v1/transact/order/autopay`, options);
  const txid = response.data.data.txid;
  return txid;
}

You will receive back the transaction information. It will also be sent to your notify_url. Please store the transaction ID (txid) in order to retrieve the data later.

Retrieving Data

You can use our Transaction Query API to find the transaction including your data. Check the link for usage details.

https://api.ddpurse.com/v1/bsvchain/get_transaction

In the response object, your data will be in the vouts array. Usually, the transaction with your data will be the first object in the array (index 0). To confirm, you can look at each object in the array and examine the script_hex property. The one that starts with 006a will be your data.

Remember to remove the 006a and decode your data from hex.

async function getData(YOUR_APP_ACCESS_TOKEN, TXID) {
  const options = {
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${YOUR_APP_ACCESS_TOKEN}`,
    },
    method: 'POST',
    data: JSON.stringify({ transaction_hash: TXID }),
  };
  const response = await axios('https://api.ddpurse.com/v1/bsvchain/get_transaction', options);
  const responseData = response.data;
  let data;
  responseData.data.vouts.forEach((vout) => {
    if (vout.script_hex.startsWith('006a')) {
      const hexDecoded = Buffer.from(
        vout.script_hex.slice(4), // slice off the '006a'
        'hex'
      ).toString('utf8');
      data = JSON.parse(hexDecoded);
    }
  });
  return data;
}

Badge

In cooperation with the sCrypt team, we have released a brand new token service: Badge.

Badge is built on BSV's sCrypt protocol.

In the first release stage, we will first open these several API endpoints. Stay tuned for more.

Create/Issue Token

Any third-party program that supports the protocol can provide query functions (query functions include transaction history, balance, etc.). All records are public and auditable, corresponding to the UTXO transaction process on the blockchain.

Query/Inspect Token

Developers can create various types of tokens by themselves. All of the token rules and descriptive information is written into the blockchain. Developers can add rules such as the validity period of the token, whether it is publicly auditable, etc.

Transfer Token Tokens can be transferred in a decentralized fashion without relying on specific servers, thus avoiding single points of failure. The token amount is recorded in UTXO instead of OP_RETURN, which can automatically synchronize and avoid various double spending, reorgs or other unwanted behavior. note: the UTXO script is different from the traditional P2PKH script. It will not cause UTXO to be spent unintentionally.

Destroy Token

The created Token is 'destroyed' by being transferred back to the issuer. The whole process is simple, convenient and efficient.

Create Badge

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/badge/create' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payload": "{\"amount\":8888,\"wallet_index\":0,\"wallet_type\":\"coin_regular\"}",
    "signature": "3045022100a9f5270f368933bdc2812b83f8e4809331157c79a64e809bbf66b7a01577626402207dba9a876e83a74f023473e4f25e28e55e933571557a9dfc500a2e831811d351",
    "pubkey": "0332c837d3ca3dfab8f4170a56f7f18384417e03b8a395af0c6fb2b1352cc867cc"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "badge_code": "c52bf511d0186a18dcd45cf7becfc12dc0f17595b353e6c26e692729cdb455ca",
    "tx_info": {
      "fee": 223,
      "rawtx": "0200000002ab60958aeb976a3bd0c96ff0d24a2fcaaee0104f68cf18c45abc9d9ba19f0875000000006a4730440220295af79f7c150b1ed7c617e4fba0c0e231fef79b5d5140a3fbf6e55903c40ab502201b0152fb8c0f6bf6973f5af70eea9b64c74f4ed177480c731bb410a43930572b4121037347726fc59f7ede2db0913903db0a42458f77011e67217812580990b9f175f4ffffffff18ea9174304057b8164bbd229849c15fbe8c1b047b68fc499a82019be0cfea8c000000006b483045022100c2e13ba1dc3e82ad55986dbfd47e05f72ad4ed054e0b586575b5ca0c5d7ac3e50220548d37a9f5e1620073f43031d668cf7cf4dffec67dc31e269d351f51c69888144121037347726fc59f7ede2db0913903db0a42458f77011e67217812580990b9f175f4ffffffff027803000000000000535101400100015101b101b261146261bdd1a5f0200383d92c9e255e236ce9e5409e005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a08b822000000000000a1260000000000001976a914d9472b1bc1115851a0efe99556d76fb4d7bc5f9a88ac00000000",
      "txid": "c52bf511d0186a18dcd45cf7becfc12dc0f17595b353e6c26e692729cdb455ca"
    }
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/badge/create

Request Body

Param Type Required Description
payload json string YES Request payload data. See: Request Payload below for details
signature string YES Signed payload string. See: Signature Authentication
pubkey string YES User public key

Request Payload

Param Type Required Description
wallet_type string YES Wallet type. Required set value: coin_regular
wallet_index int YES Wallet index. Default is 0. 0 means that wallet is webapp wallet
amount int YES Amount of tokens (badges) to create
message string NO op_return message
+badge_info object YES Badge info. This will be saved into the blockchain
└ issuer_name string NO Issuer name
└ issuer_avatar string NO Issuer avatar
└ contact_details string NO Issuer contact info
└ badge_name string NO Badge name
└ badge_name_abbreviation string NO Abbreviated badge name
└ badge_logo string NO Logo
└ badge_color string NO Color
└ badge_cover string NO Cover
└ badge_back string NO Back
└ title string NO Title
└ subtitle string NO Subtitle
└ description string NO Description
└ details string NO Detailed description
└ smallest_unit string NO Smallest unit name, e.g. in BSV=satoshi
└ default_unit string NO Default unit name, e.g. in BSV=Bitcoin
└ unit_ratio int NO Smallest to default unit ratio, e.g. in BSV 100000000(:1)

Response Body

Param Type Description
+tx_info object Transaction result
└ txid string Transaction ID txid
└ fee int Transaction fee
└ rawtx string Raw transaction
badge_code string Generated badge ID, required for subsequent actions

Transfer badge to user

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/badge/transfer_to_user' \
--header 'Content-Type: application/json' \
--data-raw '{
   "payload":"{\"badge_code\":\"ed61c3b45253570e001d50283c37c1820549f3af58adb915a9f19b4811f17f3b\",\"payees\":[{\"amount\":998,\"user_id\":\"1321773458270461952\",\"wallet_index\":0,\"wallet_type\":\"coin_regular\"}],\"wallet_index\":0,\"wallet_type\":\"coin_regular\"}",
   "signature":"304402200d10bb78e13d7e649ceb16b4c7acffb47b70506904ce3a75092dc98ed0eb7d260220582df2d21f0cd6778504aaa84d62fd2eefcfc524e1f79f5eab2dda52da268ce6",
   "pubkey":"0332c837d3ca3dfab8f4170a56f7f18384417e03b8a395af0c6fb2b1352cc867cc"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "fee": 272,
    "rawtx": "0200000002ebb93c38b383cd8681252567217620a25793ce8583c710f1ba15d4094c9718390100000070473044022052c3efdd42bf410d8d1b01aaee83377fd09a63edc8eccafdf5ab2a283fc7dafe022077eca91b9a790079530f7724e3fd104823bc04b0968e5ceee8f85aa1e4b3a2d541210362b83ac39f1f26734abaa034ad8b6bf7fbb52d0c3caf3585ed3a266195531c93056261646765ffffffff3773e900c09fe2e349f8aa107135dd749f9eb7f103630b4a23da265830556290020000006a473044022100a9ebaa52a264ff93fe920f03674a690a4e549778e990b94e21ee1962faf14efc021f50a07016e4af8c0145182fc257fb8393954863ed59da7b86ab95649e034269412102f9f7501ec42d33d90827cb6a82c3efa96c2c6c763f1400fe58d321b72806202fffffffff037803000000000000535101400100015101b101b261145e4c212664441bd01a7253975559e9f28121d5af005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a08e6030000000000007803000000000000535101400100015101b101b26114ec8240727e2502ad10b303d1817e72762f3911df005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a08d27e010000000000b4ed1f08000000001976a914ec8240727e2502ad10b303d1817e72762f3911df88ac00000000",
    "txid": "5d811a5af91e4e35e5285a135a050005abc5e5fc03d69b5c9efc2105a20dce26"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/badge/transfer_to_user

Request Body

Param Type Required Description
payload json string YES Request payload data. See: Request Payload below for details
signature string YES Signed payload string. See: Signature Authentication
pubkey string YES User public key

Request Payload

Param Type Required Description
wallet_type string YES Wallet type. Required set value: coin_regular
wallet_index int YES Wallet index. Default is 0. 0 means that wallet is webapp wallet
badge_code string YES Badge ID
message string NO op_return message
+payees object[] YES Receivers array
└ wallet_type string YES Wallet type. Required default value:coin_regular
└ wallet_index int YES Wallet index. Default is 0.
└ amount int YES Amount of tokens (badges) to transfer
└ user_id string YES Receiver ID

Response Body

Param Type Description
txid string Transaction ID txid
fee int Transaction fee
rawtx string Raw transaction

Transfer badge to address

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/badge/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
   "payload":"{\"badge_code\":\"ed61c3b45253570e001d50283c37c1820549f3af58adb915a9f19b4811f17f3b\",\"to\":[{\"amount\":1555,\"content\":\"mq5VHs1bVKy3XYwGnP3r4ysCvpGUFwLA9e\",\"type\":\"address\"}],\"wallet_index\":0,\"wallet_type\":\"coin_regular\"}",
   "signature":"304402204a1009b7173b4a57b3f8b2f6a4dde5b4650193566fc50c4958f1d91ecd8e49ac022031b292ceb1b7e9cbd9098ead020c8ecc6bbe9abfef38aa2adf9d94c11a89cc7b",
   "pubkey":"0332c837d3ca3dfab8f4170a56f7f18384417e03b8a395af0c6fb2b1352cc867cc"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "fee": 272,
    "rawtx": "0200000002ebb93c38b383cd8681252567217620a25793ce8583c710f1ba15d4094c9718390100000070473044022052c3efdd42bf410d8d1b01aaee83377fd09a63edc8eccafdf5ab2a283fc7dafe022077eca91b9a790079530f7724e3fd104823bc04b0968e5ceee8f85aa1e4b3a2d541210362b83ac39f1f26734abaa034ad8b6bf7fbb52d0c3caf3585ed3a266195531c93056261646765ffffffff3773e900c09fe2e349f8aa107135dd749f9eb7f103630b4a23da265830556290020000006a473044022100a9ebaa52a264ff93fe920f03674a690a4e549778e990b94e21ee1962faf14efc021f50a07016e4af8c0145182fc257fb8393954863ed59da7b86ab95649e034269412102f9f7501ec42d33d90827cb6a82c3efa96c2c6c763f1400fe58d321b72806202fffffffff037803000000000000535101400100015101b101b261145e4c212664441bd01a7253975559e9f28121d5af005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a08e6030000000000007803000000000000535101400100015101b101b26114ec8240727e2502ad10b303d1817e72762f3911df005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a08d27e010000000000b4ed1f08000000001976a914ec8240727e2502ad10b303d1817e72762f3911df88ac00000000",
    "txid": "5d811a5af91e4e35e5285a135a050005abc5e5fc03d69b5c9efc2105a20dce26"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/badge/transfer

Request Body

Param Type Required Description
payload json string YES Request payload data. See: Request Payload below for details
signature string YES Signed payload string. See: Signature Authentication
pubkey string YES User public key

Request Payload

Param Type Required Description
wallet_type string YES Wallet type. Required set value: coin_regular
wallet_index int YES Wallet index. Default is 0. 0 means that wallet is webapp wallet
badge_code string YES Badge ID
message string NO op_return message
+to object[] YES Receivers array
└ type string YES Receiver type, required default:address
└ content string YES Receiver address (must be DotWallet BSV address)
└ amount int YES Amount of tokens (badges) to transfer

Response Body

Param Type Description
txid string Transaction ID txid
fee int Transaction fee
rawtx string Raw transaction

Query badge balance

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/badge/get_balance' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payload": "{\"badge_code\":\"c52bf511d0186a18dcd45cf7becfc12dc0f17595b353e6c26e692729cdb455ca\",\"wallet_index\":0,\"wallet_type\":\"coin_regular\"}",
    "signature": "3044022034663aec9a59dbd1342ded18edb79909b2c45188e6b893ffbc92be5f4bd4157b02201551f9bca2ecd19c6072efdcd50caf5ec52108e5daedb45d9eb00e3b96b1ae90",
    "pubkey": "0332c837d3ca3dfab8f4170a56f7f18384417e03b8a395af0c6fb2b1352cc867cc"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "confirm": 0,
    "unconfirm": 8888
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/badge/get_balance

Request Body

Param Type Required Description
payload json string YES Request payload data. See: Request Payload below for details
signature string YES Signed payload string. See: Signature Authentication
pubkey string YES User public key

Request Payload

Param Type Required Description
wallet_type string YES Wallet type. Required set value: coin_regular
wallet_index int YES Wallet index. Default is 0. 0 means that wallet is webapp wallet
badge_code string YES Badge ID

Response Body

Param Type Description
confirm int confirmed balance
unconfirm int unconfirmed balance

Query badge transaction record

# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/badge/get_history' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payload": "{\"badge_code\":\"ed61c3b45253570e001d50283c37c1820549f3af58adb915a9f19b4811f17f3b\",\"io_type\":0,\"limit\":10,\"offset\":0,\"wallet_index\":0,\"wallet_type\":\"coin_regular\"}",
    "signature": "30440220284733c549f6ff99bcb9afc416268ac6e81b5893bed21e5ea7f539c1f3904eb602207cd569d10e845e5beba4632400d1ba07d1cfa834e474f32556088bdb4f0282f4",
    "pubkey": "0332c837d3ca3dfab8f4170a56f7f18384417e03b8a395af0c6fb2b1352cc867cc"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "count": 5,
    "data": [
      {
        "badge_code": "ed61c3b45253570e001d50283c37c1820549f3af58adb915a9f19b4811f17f3b",
        "blockhash": "",
        "height": -1,
        "timestamp": 1606361812,
        "txid": "1eef9a5c45ea735c2bf547a9c088a9e1bb37b30d441b93860615adf8c148e1e1",
        "value": -1555
      },
      {
        "badge_code": "ed61c3b45253570e001d50283c37c1820549f3af58adb915a9f19b4811f17f3b",
        "blockhash": "",
        "height": -1,
        "timestamp": 1606355830,
        "txid": "ed61c3b45253570e001d50283c37c1820549f3af58adb915a9f19b4811f17f3b",
        "value": 100000
      }
    ]
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/badge/get_history

Request Body

Param Type Required Description
payload json string YES Request payload data. See: Request Payload below for details
signature string YES Signed payload string. See: Signature Authentication
pubkey string YES User public key

Request Payload

Param Type Required Description
wallet_type string YES Wallet type. Required set value: coin_regular
wallet_index int YES Wallet index. Default is 0. 0 means that wallet is webapp wallet
badge_code string YES Badge ID
io_type int YES Record history type, 0for both outgoing and incoming,1only incoming transactions,2outgoing
offset int YES Offset amount, 1 means skip one record
limit int YES Amount to query

Response Body

Param Type Description
count int Amount of transactions
+data object[] Transactions array
└ badge_code string Badge ID
└ blockhash string Block hash,if included in a block. Unconfirmed will be empty
└ height int Block height if included in a block. Unincluded will be -1
└ timestamp int Transaction time
└ value string Badge amount. (negative amounts indicate outgoing transaction)
└ txid int Transaction ID txid

Merchant API

Join the Mempool developers group on Telegram!

This API connects developers to the BSV Merchant API and lets developers:

Query Mempool miner fees

Get the latest miner fees (Bitcoin transaction fee rates) from the Mempool mining pool.

curl --location --request GET 'https://api.ddpurse.com/v1/mapi/feeQuote'\
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' 

The above command returns JSON structured like this:

{
  "payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-28T11:15:03.722Z\",\"expiryTime\":\"2020-01-28T11:25:03.722Z\",\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"currentHighestBlockHash\":\"000000000000000001cedc3dec00ecd29943a275498e812e72b2afdf5df8814a\",\"currentHighestBlockHeight\":619574,\"minerReputation\":\"N/A\",\"fees\":[{\"feeType\":\"standard\",\"miningFee\":{\"satoshis\":1,\"bytes\":1},\"relayFee\":{\"satoshis\":1,\"bytes\":1}},{\"feeType\":\"data\",\"miningFee\":{\"satoshis\":1,\"bytes\":1},\"relayFee\":{\"satoshis\":1,\"bytes\":1}}]}",
  "signature": "304402202a7f70855739a6948c00c2a85dd733f087c4f1ae4beb256c225eadab767d5e1d02207870c57728166f61b0334bd89640d6d6c26f31ada4aac42b29971ebfa5c414e1",
  "publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
  "encoding": "UTF-8",
  "mimetype": "application/json"
}

HTTP Request

Get https://api.ddpurse.com/v1/mapi/feeQuote

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Response Body

Param Type Description
payload string main data payload encoded in a specific format type
signature string signature on payload string. This may be null.
publicKey string public key to verify signature. This may be null.
encoding string encoding type
mimetype string Multipurpose Internet Mail Extensions type

Payload

Param Type Description
apiVersion string version of merchant api spec
timestamp string timestamp of payload document
expiryTime string expiry time of quote
minerId string minerID / public key of miner. This may be null.
currentHighestBlockHash string hash of current blockchain tip
currentHighestBlockHeight int hash of current blockchain tip
minerReputation string reputation of miner
fees object[] fees charged by miner (feeSpec BRFC)

Query transaction status

curl --location --request GET 'https://api.ddpurse.com/v1/mapi/tx/594aa632facc2bdbce31ee02f7865997c0fa17a3360acb2f621cb117ad25c277'/
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' 

The above command returns JSON structured like this:

{
  "payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-15T11:41:29.032Z\",\"returnResult\":\"failure\",\"resultDescription\":\"Transaction in mempool but not yet in block\",\"blockHash\":\"\",\"blockHeight\":0,\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"confirmations\":0,\"txSecondMempoolExpiry\":0}",
  "signature": "3045022100f78a6ac49ef38fbe68db609ff194d22932d865d93a98ee04d2ecef5016872ba50220387bf7e4df323bf4a977dd22a34ea3ad42de1a2ec4e5af59baa13258f64fe0e5",
  "publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
  "encoding": "UTF-8",
  "mimetype": "application/json"
}

HTTP Request

GET https://api.ddpurse.com/v1/mapi/tx/{hash}

Request Path Params

Param Type Required Description
hash string YES The transaction hash (txid)

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Response Body

Param Type Description
payload string main data payload encoded in a specific format type
signature string signature on payload string. This may be null.
publicKey string public key to verify signature. This may be null.
encoding string encoding type
mimetype string Multipurpose Internet Mail Extensions type

Payload

Param Type Description
apiVersion string version of merchant api spec
timestamp string timestamp of payload document
returnResult string will contain either success or failure
resultDescription string will contain the error on failure or empty on success
blockHash string hash of tx block
blockHeight int hash of tx block
minerId string minerId public key of miner
confirmations int number of block confirmations
txSecondMempoolExpiry int Duration (minutes) Tx will be kept in secondary mempool

Send transaction Rawtx

curl --location --request POST 'https://api.ddpurse.com/v1/mapi/tx'
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rawtx":"020000000111f4be4399b8f466ba2788a6398caa4bf901d04003c653e78b6bb18da2bf9940000000006b483045022100ecdd8c9b34a8a8b10478b8a2bb06af18f294bffd19784bc68b58cba41a70165b022054679dad5e210236321eb09156beab18ea152fb76a97ced3ed418c85fad4ced9412102877b34ce9d3c57813e5730ee41fdc387f4a0f1fa23280774433c415d8e812bd5ffffffff0258020000000000001976a9147499270faa0ca65be4329ad2e1afa71869d1470e88ac15900300000000001976a9142d42015fe20db9eea5694f850fddf2729989fa6388ac00000000"
}'

The above command returns JSON structured like this:

{
  "payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-15T11:40:29.826Z\",\"txid\":\"6bdbcfab0526d30e8d68279f79dff61fb4026ace8b7b32789af016336e54f2f0\",\"returnResult\":\"success\",\"resultDescription\":\"\",\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"currentHighestBlockHash\":\"71a7374389afaec80fcabbbf08dcd82d392cf68c9a13fe29da1a0c853facef01\",\"currentHighestBlockHeight\":207,\"txSecondMempoolExpiry\":0}",
  "signature": "3045022100f65ae83b20bc60e7a5f0e9c1bd9aceb2b26962ad0ee35472264e83e059f4b9be022010ca2334ff088d6e085eb3c2118306e61ec97781e8e1544e75224533dcc32379",
  "publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
  "encoding": "UTF-8",
  "mimetype": "application/json"
}

HTTP Request

POST https://api.ddpurse.com/v1/mapi/tx

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Param Type Required Description
rawtx string YES Transaction raw hex

Response Body

Param Type Description
payload string main data payload encoded in a specific format type
signature string signature on payload string. This may be null.
publicKey string public key to verify signature. This may be null.
encoding string encoding type
mimetype string Multipurpose Internet Mail Extensions type

Payload

Param Type Description
apiVersion string version of merchant api spec
timestamp string timestamp of payload document
txid string transaction ID
returnResult string will contain either success or failure
resultDescription string will contain the error on failure or empty on success
minerId string minerId public key of miner
currentHighestBlockHash string hash of current blockchain tip
currentHighestBlockHeight int hash of current blockchain tip
txSecondMempoolExpiry int Duration (minutes) Tx will be kept in secondary mempool

Please see the official Merchant API Github for details:https://github.com/bitcoin-sv-specs/brfc-merchantapi

Blockchain Queries

Block Header

Get the raw block header using the block hash

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_raw_block_header' \
    -H'Content-Type: application/json' \
    -H "Authorization: Bearer APP-ACCESS-TOKEN" \
    -d'{
        "blockhash": "<YOUR-blockhash>"
    }'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "header_hex": "02000000028f2cb75e0b6b2bcaba83efa34cb6af4a7bc04e882de8c2090000000000000023d7fee87f54bfb980f383b80742ac060bb5294ff9cb82d159caa8acaf1eec1647f9fc51f2db"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsvchain/get_raw_block_header

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Param Type Required Description
blockhash string yes block hash

Response Body

Param Type Description
header_hex string hexadecimal block header

Block Info from Hash

Query block information using a block hash

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_block_by_hash' \
    -H'Content-Type: application/json' \
    -H "Authorization: Bearer APP-ACCESS-TOKEN" \
    -d'{
    "hash": "<YOUR-hash>"
    }'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "height": 625882,
    "reward": 1250601893,
    "timestamp": 1583999952,
    "transaction_count": 1771,
    "size": 1015875,
    "hex_coinbase": "03da8c092f68747470733a2f2f636f696e6765656b2e636f6d2f6d696e65722d6f757472656163682f2f4b37633144d892a7db975fcb22337800c0",
    "hash": "0000000000000000017d4326a7232eaefde92465ae77d762c6d1892914e5f0e5",
    "difficulty": 415922505851.8293
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsvchain/get_block_by_hash

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Param Type Required Description
hash string string block hash

Response Body

Param Type Description
height int height
hash string block hash
size int size (unit: byte)
timestamp int timestamp
reward int Block reward (unit: satoshi)
hex_coinbase string Hexadecimal encoding script
transaction_count int Transaction count
difficulty float64 difficulty of mining in this block

Block Info from Height

Query block information based on height

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_block_by_height' \
-H'Content-Type: application/json' \
-H "Authorization: Bearer APP-ACCESS-TOKEN" \
-d'{
"height": "<YOUR-height>"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "height": 625882,
    "reward": 1250601893,
    "timestamp": 1583999952,
    "transaction_count": 1771,
    "size": 1015875,
    "hex_coinbase": "03da8c092f68747470733a2f2f636f696e6765656b2e636f6d2f6d696e65722d6f757472656163682f2f4b37633144d892a7db975fcb22337800c0",
    "hash": "0000000000000000017d4326a7232eaefde92465ae77d762c6d1892914e5f0e5",
    "difficulty": 415922505851.8293
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsvchain/get_block_by_height

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Param Type Required Description
height int int block height

Response Body

Param Type Description
height int height
hash string block hash
size int size (unit: byte)
timestamp int timestamp
reward int Block reward (unit: satoshi)
hex_coinbase string Hexadecimal encoding script
transaction_count int Transaction count
difficulty float64 difficulty of mining in this block

Block Info Batch Query from Height

Get block information in batches based on block height

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_blocks_by_height' \
-H'Content-Type: application/json' \
-H "Authorization: Bearer APP-ACCESS-TOKEN" \
-d'{
"offset": "<YOUR-OFFSET>",
"limit":"<YOUR-LIMIT>"
}'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": [
    {
      "height": 625890,
      "reward": 1250171398,
      "timestamp": 1584005058,
      "transaction_count": 782,
      "size": 284711,
      "hex_coinbase": "03e28c0904b8ff695e322f537069646572506f6f6c2ffabe6d6dda153ebb0e68d606ba543955fc4aece1fa6ebf31c8dec55114914bb4cfc20a2401000000000000000100076acb69000000000000",
      "hash": "00000000000000000080a268f9d00b7e05a3362884cd525fa540308205af8e04",
      "difficulty": 415922505851.8293
    },
    {
      "height": 625889,
      "reward": 1250319195,
      "timestamp": 1584004809,
      "transaction_count": 802,
      "size": 368455,
      "hex_coinbase": "03e18c0904c9fe695e088100079a7606000057617270486173685c30",
      "hash": "00000000000000000226910abdfddb05cea178e3eb7f9086b8600a9970fecd9c",
      "difficulty": 415922505851.8293
    }
  ]
}

HTTP Request

POST https://api.ddpurse.com/v1/bsvchain/get_blocks_by_height

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Param Type Required Description
offset int int Offset, for example: [1,2,3,4,5] offset: 2, limit: 3 to get [3,4,5]
limit int yes entries, maximum is 100

Response Body

Param Type Description
height int height
hash string block hash
size int size (unit: byte)
timestamp int timestamp
reward int Block reward (unit: satoshi)
hex_coinbase string Hexadecimal encoding script
transaction_count int Transaction count
difficulty float64 difficulty of mining in this block

Block Transaction List

Get block transaction list using the block hash

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_blocks_txs' \
    -H'Content-Type: application/json' \
    -H "Authorization: Bearer APP-ACCESS-TOKEN" \
    -d'{
        "hash":"<YOUR-HASH>",
        "offset": "<YOUR-OFFSET>",
        "limit":"<YOUR-LIMIT>"
    }'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "Txs": [
      "4ef83acd026495adff7dfb276bfaf271b0e6ba6c2bc462ef105dd8e1c5fc29f4",
      "9de197b307f650835765150bff25220408eb6d2d753990645d38bd085ff72053",
      "1d6982b15f828b77f48146cee3f4f8a4658c0a9dce287e59b27dc14ee9654780",
      "51679f5421403d13b204827f5e09f0c1316a311645f850ec925007d6ae135fe4",
      "81a95fab656ca6fe6060d9d202419e00a34c400d3c8215b33ec06e5f10a4b033"
    ]
  }
}

Http Request

POST https://api.ddpurse.com/v1/bsvchain/get_blocks_txs

Request Body

Param Type Required Description
hash string i block hash
offset int is offset, for example: [1, 2, 3, 4, 5] offset: 2, limit: 3 to get [3,4,5]
limit int yes entries, maximum is 100

Response Body

Param Type Description
txs string[] txid array

Blockchain Basic Info

Query some basic information of the blockchain

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_chain_info' \
-H'Content-Type: application/json' \
-H "Authorization: Bearer APP-ACCESS-TOKEN" \

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "bestblock": 625891,
    "unconfirm_tx_count": 37525,
    "bestfeerate": {
      "feebyte": 1,
      "feesatoshi": 1
    },
    "hashes_per_sec": 2829162.275754181,
    "diffculty": 415922505851.8293,
    "nbits": 418216206
  }
}

POST https://api.ddpurse.com/v1/bsvchain/get_chain_info

Response Body

Param Type Description
bestblock int latest height
unconfirm_tx_count int Number of unconfirmed transactions
BestFee json btc: Indicates the transaction fee rate of the current memory pool transaction less than 0.8m; bsv: fixed return 1:1
feebyte int In conjunction with feesatoshi, it means few bytes in few satoshis/few bytes
feesatoshi int In conjunction with feebyte, it means how many satoshis in how many bytes
hashes_per_sec float Hash power
diffculty float difficulty

Transaction inquiry

Query transaction information through txid

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_transaction' \
    -H'Content-Type: application/json' \
    -H "Authorization: Bearer APP-ACCESS-TOKEN" \
    -d'{
        "transaction_hash": "<YOUR-TXID>"
    }'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "txid": "016a195a865e57a24d2f606aef89d8775ed2f8ae9016419542b9ad798574f6f6",
    "vins": [
      {
        "index": 0,
        "script": "4730440220493447148876bb55b63712c93004384ad0e0b35500ce96949751682afe8e7d4d022050ff787468c73a3ca51207a93805e96de032a2fa2a6fd8a0153447148876bb55b63712c93004384ad0e0b35500ce96949751682afe8e7d4d022050ff787468c73a3ca51207a93805e96de032a2fa2a6fd8a0153447148876bb55b63712c93004384b704fd57dbadfcc95106df8",
        "value": 1110213
      },
      {
        "index": 1,
        "script": "4730440220449daee99fd72d026864fa084ec5a338be4e3c355ff3a7f6d01951c25957b6b702200fe26fb621da1c2df8d870a5bf6029bb6fb775a58c320f5589e90fb8df3cd46783ced46dcd72d026864fa084ec5a338be4e3c355ff3a7f6d01951c25957b6b702200fe26fb621da1c2df8d870a5bf6029bb6fb775a58c320f5589e90fb8dcd46783ceecdcd",
        "value": 3602800
      },
      {
        "index": 2,
        "script": "483045022100c3d55580d62ac027676e5d352be4cc710051726c68d5ff76085682dd4b3636fb02203b5ff2f5b298a42efbabde5273efda8329547de469f32279cae25d5b3984edfd41210286f4ff4b3984edfd41210286f4ff4dafebf4252900734614546",
        "value": 1424703
      },
      {
        "index": 3,
        "script": "473044022047ae5c1c2ac3211418708141633fe6952f8dd8e7d9baa878d2323323f25c3c38022076af30794eabb63dc9d840152c1b29921adeb67c93e8eb39efaa5c1c2ac3211418708141633fe6952f8dd8e7d9baa878d2323323f25c3c38022076af30794eabb63dc9d840152c1b29921adeb67c93e8eb39efaa5c1c2ac3211418708141633c",
        "value": 254000
      },
      {
        "index": 4,
        "script": "483045022100d9522a1e107375b184459091855c36c0a2fff577d9270ca140c4f6a253986a1e02200cd4934de777f188fe5d85fc8bbe111569c58b48cb46c0b3cfdc7ef60fb024b024350024a",
        "value": 144110712
      }
    ],
    "vouts": [
      {
        "index": 0,
        "script": "76a9142fa431e514155b7d36955a7b204aca593043128288ac",
        "value": 149500000
      },
      {
        "index": 1,
        "script": "76a914cb13d2b179851b7b37a34763a698fabfe401c7bf88ac",
        "value": 1001610
      }
    ],
    "height": 625876,
    "size": 815,
    "timestamp": 1583995981,
    "confirmation": 6
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsvchain/get_transaction

Request Header

Parameter Type Required Description
Authorization String YES Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant

Request Body

Param Type Necessary Description
transaction_hash string YES Transaction hash (txid)

Response Body

Param Type Description
vouts json all vout
vins json all vin
index int index of vin or vout
confirmation int confirmation number
timestamp int timestamp
size int Transaction size (unit: byte)
value int Transaction amount (unit: satoshi)
script string Hex coded script
txid string txid of the transaction
height int Block height, -1 means unconfirmed

Merkle branch inquiry

Query merkle branch through txid

curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_standard_merkle' \
    -H'Content-Type: application/json' \
    -H "Authorization: Bearer APP-ACCESS-TOKEN" \
    -d'{
        "txid": "<YOUR-TXID>",
        "version": "<YOUR-response version>",
    }'

The above command returns JSON structured like this:

{
  "code": 0,
  "msg": "",
  "data": {
    "version": "2",
    "path": [
      "40945619323560e0db6ae9b8c799fb8e16805b5d32d56531dfd163d5962abf3f",
      "e9190b50c4afcc9c8002183e347751f1f0fcd571a141c1a56487c057cd1c9a7b",
      "d0b727bc96ace4645cd2b2cf82640244e500302c7c76ccdf2cc0ef4c6698ee3e",
      "50395af86c9ac148912a223ad25cb710dae5e5cb8baf9be12c30fc9d938f9979",
      "49f59b0658ab1d600a4cd7c83aea6cabc162692f14ec7d05a821055557802161",
      "fc47f132653df9c642c36324c573f035f2d77edcc5e16547ba90d51e7792d93b",
      "f54ce0169498a1b0123039ae5af65ff600b81602d75ce65b61577cbe43dca3b0",
      "69c58f65a36832e371ff0db05c12b1685ad733b12069adce29a5eaa6b3b97379",
      "e72b51b44e7710d6992f098e11ba1941185f7a19ac892a3d8981bb6ee3f9057e",
      "1649dca1ee35b6363e3ebcabe75db9351e03a4441ec2d1f264023e4f0ba13b67",
      "",
      "",
      "",
      "7b2256657273696f6e223a3830353239383137362c2250726576426c6f636b223a5b36322c3232322c3132382c3136312c32322c31352c3139322c3139352c3130382c36372c3134362c37372c3130312c3139312c37382c36342c3235302c35382c31312c32372c32302c38362c32372c312c302c302c302c302c302c302c302c305d2c224d65726b6c65526f6f74223a5b3134392c3231372c39312c34352c34382c36392c3230382c332c3233332c31352c3131302c3233342c3137332c3130322c32382c32362c3133312c3234342c3233382c302c3131352c36362c3234372c3134322c3137332c3139302c38332c3232362c3233362c3234312c39342c3133335d2c2254696d657374616d70223a22323032302d30392d31355430353a33303a35395a222c2242697473223a3430323932333332382c224e6f6e6365223a333234333235363439317d"
    ],
    "index": 1,
    "header": "eyJWZXJzaW9uIjo4MDUyOTgxNzYsIlByZXZCbG9jayI6WzYyLDIyMiwxMjgsMTYxLDIyLDE1LDE5MiwxOTUsMTA4LDY3LDE0Niw3NywxMDEsMTkxLDc4LDY0LDI1MCw1OCwxMSwyNywyMCw4NiwyNywxLDAsMCwwLDAsMCwwLDAsMF0sIk1lcmtsZVJvb3QiOlsxNDksMjE3LDkxLDQ1LDQ4LDY5LDIwOCwzLDIzMywxNSwxMTAsMjM0LDE3MywxMDIsMjgsMjYsMTMxLDI0NCwyMzgsMCwxMTUsNjYsMjQ3LDE0MiwxNzMsMTkwLDgzLDIyNiwyMzYsMjQxLDk0LDEzM10sIlRpbWVzdGFtcCI6IjIwMjAtMDktMTVUMDU6MzA6NTlaIiwiQml0cyI6NDAyOTIzMzI4LCJOb25jZSI6MzI0MzI1NjQ5MX0=",
    "repeated_indexes_count": 0,
    "duplicated_indexes": null
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsvchain/get_transaction

Request Body

Param Type Necessary Description
txid string YES Transaction hash (txid)
version string YES response version:"0","1"...

Response Body

Param Type Description
version string the version you set in the request
path string[] merkle branches
index int the index of the transaction in the block
header byte[] block header bytes

DAPP API

获取 utxos

获取 utxos

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_list_unspent' \
-H "Authorization: Bearer <USER-ACCESS-TOKEN>"
--data-raw '{
    "min_amount": 0
}'

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "utxos": [
      {
        "tx_hash": "6e6ca644fbce1311a8078a93868244f6f3f11484aaa6b5fb0bbe9e51c1e70396",
        "output_index": 2,
        "satoshis": 8374,
        "script": "76a9146b1bb91452b7585b326b3bda87c761e6aa03ef9388ac",
        "addr": "1AmLWkaTnJKPX45cTXLoWbpLoM2X4QyBve",
        "pubkey": "03acc481ada69bea5ec190f3470eaed4b6c19636c3cd80daf5d4db7303a139f0bd"
      }
    ]
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_list_unspent

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer USER-ACCESS-TOKEN,授权方式: 用户授权

Request Body

参数名 类型 是否必须 说明
min_amount int 需要的 utxo 的总量

Response Body

参数名 类型 说明
tx_hash string
output_index int
satoshis int
script string
addr string
pubkey string

获取用户 rawtx

获取用户 rawtx

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_sign_raw_transaction' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rawtx":"<YOUR RAWTX>",
    "input_index":0,
    "sig_type":1,
    "addr":"<ADDR>"
}'

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "signed_rawtx": "SIGNED_RAWTX"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_sign_raw_transaction

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer APP-ACCESS-TOKEN,授权方式: 应用授权

Request Body

参数名 类型 是否必须 说明
rawtx string 需要的签名的 rawtx
input_index int 第几个 vin 需要签名
sig_type int 签名的类型,1 代表 sig_all
addr string 地址

Response Body

参数名 类型 说明
signed_rawtx string 签好后的 tx

获取用户 signature

获取用户 signature

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_get_signature' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rawtx":"<RAWTX>",
    "input_index":0,
    "sig_type":1,
    "addr":"<ADDR>"
}'

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "hex_signature": "HEX_SIGNATURE"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_get_signature

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer APP-ACCESS-TOKEN,授权方式: 应用授权

Request Body

参数名 类型 是否必须 说明
rawtx string 需要的签名的 rawtx
input_index int 第几个 vin 需要签名
sig_type int 签名的类型,1 代表 sig_all
addr string 地址

Response Body

参数名 类型 说明
signed_rawtx string 签好后的 tx

广播交易

Broadcast transaction

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_send_raw_transaction' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rawtx":"<YOUR RAWTX>"
}'

Request Body

参数名 类型 是否必须 说明
rawtx string rawtx

Response Body

参数名 类型 说明
txid string txid

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "txid": "TXID"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_send_raw_transaction

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer APP-ACCESS-TOKEN,授权方式: 应用授权

Request Body

参数名 类型 是否必须 说明
rawtx string rawtx

Response Body

参数名 类型 说明
txid string txid

获取地址

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_get_raw_change_address' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{}'

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "address": "1Fpik4DBHH2PyBf8gxNRaV8DdzDa1Bm9w7"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_get_raw_change_address

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer APP-ACCESS-TOKEN,授权方式: 应用授权

Response Body

参数名 类型 说明
address string 地址

查询用户余额

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_get_balance' \
--header 'Authorization: Bearer <USER-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{}'

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "confirm": 515937433,
    "unconfirm": 0
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_get_balance

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer USER-ACCESS-TOKEN,授权方式: 用户授权

Response Body

参数名 类型 说明
confirm int 已确认数量
unconfirm int 未确认数量

查询用户公钥

# 每次请求,提交正确的header(shell例子):
curl --location --request POST 'https://api.ddpurse.com/v1/grandet_dapp/dapp_get_public_key' \
--header 'Authorization: Bearer <USER-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{}'

请求回返是 JSON,例:

{
  "code": 0,
  "msg": "",
  "data": {
    "public_key": "035edcabbe3795595e2236cbe34f5b7f288487a2aeae7f3c8b8d7313c62e7b1968"
  }
}

HTTP Request

POST https://api.ddpurse.com/v1/grandet_dapp/dapp_get_public_key

Request Header

参数名 类型 是否必须 说明
Authorization string Authorization: Bearer USER-ACCESS-TOKEN,授权方式: 用户授权

Response Body

参数名 类型 说明
confirm int 已确认数量
unconfirm int 未确认数量

SDKs, Tools, and Libraries

The DotWallet team has provided the following resources to help you get up and running fast. Most of them are available at our GitHub

These libraries are provided for convenience and reference. They have not undergone the same rigorous testing and auditing that our core products have. If using in a production setting please read through the source code carefully, understand what it does, and use at your own risk. Pull requests are much appreciated.

JavaScript Components

Drop the @dotwallet/js library into your project, and quickly implement login and payments.

The library works as a <script> tag, and as a node import. The library includes svgs for login and payment buttons.

Note: you will still need a backend server to authenticate your transactions. Your client_secret cannot be used client-side. Set up a server quickly with the node.js sdk or our pre-made Docker server

Vue Components

This Vue component library works similarly to the javascript library but is even more convenient for use in Vue.js apps

Note: you will still need a backend server to authenticate your transactions. Your client_secret cannot be used client-side. Set up a server quickly with the node.js sdk or our pre-made Docker server

Node.js SDK

A node.js SDK for quickly building a server that uses DotWallet for Developers' APIs for logins, payments, and other blockchain services.

This SDK automatically handles the refreshing of user and app access tokens and provides common error handling.

Examples are provided in express.js, but the SDK is easily applicable to any Node.js server framework.

GitHub

Docker microservice server

Run a lightweight DotWallet authentication server as a microservice.

Try out http requests on our live test server and inspect the available requests on its auto-generated API docs page.

This can be a great option to get started quickly. It can be hosted on a cloud service provider within minutes.

If your backend is not in a language that we have an SDK for (currently only Node.js) this can be a great option. See the readme for how to forward the authentication token to your main backend server.

GitHub

Tutorials

A collection of tutorials for using DotWallet for Developers APIs. Most of the code for these examples can be found at our Github

Vanilla JavaScript (no libraries)

This is a simple guide for developers looking to add DotWallet login and payment features to an app. Examples are in JavaScript. More complete code (which includes error handling) for these examples can be found here.

Get developer keys

First, sign up with DotWallet for Developers to apply for a client ID and client secret key.

Click the “JOIN NOW” button in the top right corner of the DotWallet for Developers homepage. Once you have completed your application, sign in and click on “Applications” in the nav bar and “+Add application” on that page. The client ID and secret will be sent to your provided email.

Add ‘login with DotWallet’ to your app

The login button

Add a simple button to your app’s frontend, and wrap it in an <a> link that redirects the browser to DotWallet’s authentication screen.

<a id="login-link" >
  <img src="src/assets/dotwallet-login.png" alt="dotwallet-login" />
</a>
<!-- You'll need uuid or another random string generator for the next step -->
<!-- <script src="https://unpkg.com/uuid@latest/dist/umd/uuidv4.min.js"></script> -->
const scope = encodeURIComponent('user.info autopay.bsv autopay.btc autopay.eth'); // the permissions we'd like to ask the user for
const redirectURI = encodeURIComponent(`${YOUR_APP_URL}/your-login-landing-page`); 
const loginState = uuidv4(); // 'state' should be a random string. used to confirm that the login request was made from the same source and avoid csrf attacks
localStorage.setItem('loginState', loginState); // save the 'state' to compare later
const loginURL = `https://api.ddpurse.com/authorize?client_id=${YOUR_CLIENT_ID}&redirect_uri=${redirectURI}&response_type=code&state=${loginState}&scope=${scope}`; // construct the link
document.getElementById('login-link').href = loginURL;

Download the button image from our UI resources page

Note for local development

You cannot use localhost as the redirect_uri For local development, find your machine’s IP by putting the following command into the terminal:

ifconfig | grep netmask

You’ll get a result like this

  inet 127.0.0.1 netmask 0xff000000
  inet 192.168.1.142 netmask 0xffffff00 broadcast 192.168.1.255

Use 192.168.1.142 + your PORT number and route as the redirect_uri, for example http://192.168.1.142:3000/auth/ Login to your DotWallet for Developers account and click on “Applications”. Select your application, then go to “Display Information”, hit the edit button and add your domain to the Callback domain field. Do not add http, so in this case just add 192.168.1.142:3000/auth/. make sure you hit save, and refresh the page to make sure it saved.

Get code and compare state

Once the user approves, the browser will be sent to your provided redirect_uri with a one time code and the state as query parameters.

const urlParams = new URLSearchParams(window.location.search);
const state = urlParams.get('state');
const code = urlParams.get('code'); 
const savedState = localStorage.getItem('loginState');

if (state != savedState) { // if the state is the same as from step 1...
  alert('error validating request');
} else {
  fetch(`${YOUR_BACKEND_SERVER}/auth`, { // ...then send the code to your backend server
    method: 'POST',
    body: JSON.stringify({ code }),
    headers: {
      'Content-type': 'application/json; charset=UTF-8',
    },
  });
}

Get user access token (from backend)

Warning: This must be done from your backend server. Also remember to use .env files and never upload your client secret to GitHub.

Say we have this simple Express.js server:

const express = require('express');
const axios = require('axios');
const path = require('path');
const dotenv = require('dotenv');
const app = express();
const PORT = process.env.PORT || 3000;

const YOUR_CLIENT_SECRET = process.env.CLIENT_SECRET;
const YOUR_CLIENT_ID = process.env.CLIENT_ID;
const DOTWALLET_API = 'https://api.ddpurse.com/v1'
// ...
// routes logic will go here here
// ...
app.listen(PORT, () =>
  console.log(`DotWallet example app listening at PORT: ${PORT}`)
);

Create a POST endpoint to accept the code.

app.post('/auth', async (req, res) => {
 const data = {
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET,
    grant_type: 'authorization_code',
    code: code,
    redirect_uri: `${YOUR_APP_URL}/your-login-landing-page`, // must be the same url from step one
  };
  const accessTokenRequest = await axios.post(`${DOTWALLET_API}/oauth2/get_access_token`, data);
  const userAccessToken = accessTokenRequest.data.data.access_token

  // With our access_token we can look up the user’s profile information.

  if (userAccessToken) {
    const options = {
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${accessToken}`,
      },
      method: 'POST',
    };
    const userInfoRequest = await axios(`${DOTWALLET_API}/user/get_user_info`, options);
    const userInfo = userInfoRequest.data.data
  }
});

Success! You have confirmed the user's identity. Based on the permissions user.info autopay.bsv autopay.btc autopay.eth, you have been granted permission to their basic profile information, and can perform automatic payments on their behalf.

Add a payment button

Make a simple button:

<button id="banana-button" type="button">546 satoshis</button>

546 satoshis is the minimum payment amount

Create order and send to backend

Handle the button click in the script and make an object with your payment order details. Send the order details to your backend. Your backend will send the order details to the DotWallet API, and will receive an order ID order_sn back.

document.getElementById('banana-button').addEventListener('click', async () => {
  const orderData = {
    out_order_id: uuidv4(),
    coin_type: 'BSV',
    to: [
      {
        type: 'address',
        content: '1L3z6DzHpfr7pkkZmKfVGMjwY1984D5YRv', // REPLACE WITH YOUR WALLET ADDRESS!!!!!!!
        amount: 546,
      },
    ],
    product: {
      id: uuidv4(),
      name: 'bananas',
    },
    notify_url: YOUR_SERVER_URL + '/payment-result',
    redirect_uri: window.location.href,
  };
  const orderSnResponse = await fetch(
    YOUR_SERVER_URL + '/create-order', 
    {
      method: 'POST',
      body: JSON.stringify(orderData),
      headers: {
        'Content-type': 'application/json; charset=UTF-8',
      },
    }
  );
  const orderSnData = await orderSnResponse.json();

  // When our backend returns the order_sn, send the user to confirm the payment
  window.location.href = `${DOTWALLET_API}/v1/transact/order/apply_payment?order_id=${orderSnData.order_sn}`;
}

Get API access token (from backend)

Developer/app authentication is a prerequisite for most DotWallet API endpoints. Use your client_secret and client_id to get an auth token.

let appAccessToken = '';
async function getAppAccessToken() {
  const data = {
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET,
    grant_type: 'client_credentials',
  };
  const accessTokenRequest = await axios.post(`${DOTWALLET_API}/oauth2/get_access_token`, data);
  appAccessToken = accessTokenRequest.data.data.access_token;
}

Send order to DotWallet (from backend)

This uses your client secret key and must be done from the backend server side.

Set up our Express.js app endpoint to receive the order and send it to DotWallet’s API in return for an order_sn.

app.post('/create-order', async (req, res) => {
  const options = {
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${appAccessToken}`,
    },
    method: 'POST',
    data: { ...orderData },
  };
  const orderSnResponse = await axios(`${DOTWALLET_API}/transact/order/create`, options);
  const orderSn = orderSnResponse.data.data;
  res.json({ order_sn: orderSn })
});

That’s it! Your app can now handle login and basic payments.

Errors

HTTP status codes that DotWallet Api may return:

HTTP Status Description
403 Forbidden
404 Not Found
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

DotWallet Api may return code business error codes:

code Description
75000 Invalid access token

Contact

You can contact DotWallet for support in the following ways: Email: business@boquaninc.com Telegram: https://t.me/mempool_developer