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.

You can 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 pay out 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 payment

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-transaction based applications and server-to-server use cases. Using DotWallet’s advanced networking technology, micropayments on our API can break through the Bitcoin network’s limit on transactions.

See Automatic Payments for more.

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 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 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;

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)

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>

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)

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.

Schema

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

Protocol

All API access is over HTTPS

HTTP Request

For APIs that supports GET request, parameters can be sent via http query string
For APIs that support POST requests, parameters that are not in the URL must be sent using JSON, and the Http header Content-Type set to application/json

HTTP Response

How to judge whether the HTTP request is successful?

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

In a successful request:

HTTP status code will be 200
The code field in the body of the returned JSON will be 0

Authentication

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

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

Bearer is followed by a space, YOUR-ACCESS-TOKEN is the access_token in JWT form

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

There are currently no rate limits to use the APIs

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.

1: Apply for a developer account: https://developers.dotwallet.com/register
2: Create an application. After it is created, please check the email address you provided to obtain the client_id/client_secret

Application Authorization

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(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>"
}'

{
  "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

+----------+
| 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.

User login: Users can quickly and safely log into your application.
Get user information: Access user information that the user approves to share - Get User Information.
Automatic payment: The user can authorize the application to enable - Automatic Payments.

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

Apply for the corresponding scope permissions as needed, and the scope requires the user's consent and authorization

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

<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>

After clicking the link, the user will be directed to the DotWallet authorization page. DotWallet will ask the user to log in, and then ask whether they agree to authorize the application for the listed permission scopes.

Step 3: Recieve the code through the callback uri

# 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

After the user agrees to authorization in step 2, DotWallet will redirect the client to the redirect_uri specified by the application. The authorization code code and the provided state will be included in the query parameters.
After receiving the parameters, please check whether the state sent in step 2 and the state recovered in step 3 are consistent.

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"
}'

{
  "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"
}'

{
  "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"
  }
}

Note: To avoid security issues, this operation must be done on the server side of the application, and client_secret must not be disclosed.

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

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>"

{
  "code": 0,
  "msg": "",
  "data": {
    "id": "1278104675169476608",
    "nickname": "hello world",
    "avatar": "https://your_avatar",
    "web_wallet_address": {
      "bsv_regular": "14s59qZEA1m7B8zAAUVMtonWrKfnEdPzxh",
      "btc_regular": "18nneDCo7UmhyUjdeupNgkThAsGcc3rAVT",
      "eth_regular": "0xc1CD83264a329B4cB319b9FD3fbf16AbD7808FcF"
    }
  }
}

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
+web_wallet_address	Object	The user's receiving address on the web of DotWallet
└ bsv_regular	string	The user's BSV receiving address on the web of DotWallet
└ btc_regular	string	The user's BTC receiving address on the web of DotWallet
└ eth_regular	string	The user's ETH receiving address on the web of DotWallet

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 Autopayments, the user only needs to authorize once and the application can initiate transactions on their behalf.

Single Payment Order

Step 1：Create an order, submit it to DotWallet, and obtain an order_id
Step 2：Construct a payment URL and redirect the user to it to confirm payment
Step 3：Receive and handle payment confirmation

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, must be `address`or`script`
└ content	string	YES	Receiver address or script content. If `type` is `address`, this should be a valid address. if `type` is `script`，This should be a hex script. `script` is only supported for BSV
└ 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	NO	Address to send payment result notification to
redirect_uri	string	NO	Address to redirect browser to after payment completion
expires	int	NO	Order expiry time. Unix epoch time in seconds. Leave this blank or submit `0` and the order will not expire

Note:
In to[*].type, script is only supported for BSV transactions. BTC, ETH only support address type transactions.
For Badges transactions, use address for to[*].type and to[*].content must be a valid DotWallet user address.

Response Body

{
  "code": 0,
  "msg": "",
  "data": "1318817847320780800"
}

Param	Type	Description
data	string	Order ID (`order_id`)

Step 2：Construct payment URL, redirect user

<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

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"
}'

{
    "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
└ 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 Payments

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

Step 1：Redirect DotWallet user to the authorization page to obtain user authorization and make sure to add the scope for auto payments related permissions

Step 2：Obtain access_token through user authorization and call the Get User Information API endpoint to get the user ID. Save the authorized user ID for subsequent use
Step 3：Call the automatic payment API endpoint to initiate payment

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/"
}'

{
  "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, must be `address`or`script`
└ content	string	YES	Receiver address or script content. If `type` is `address`, this should be a valid address. if `type` is `script`，This should be a hex script. `script` is only supported for BSV
└ 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

Note: BTC, ETH only support address transactions, not script. to[*].typemust beaddress。

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

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

{
  "code": 0,
}

Handle insufficient balance

If the payment request from the previous step returns an error with the code 10180007 then the user's autopay wallet balance 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.

Redirect the user to this URL: https://ddpurse.com/wallet/open/transfer?redirect_url=<YOUR_REDIRECT_URL>

URL Parameters

Parameter	Required	Description
redirect_url	NO	The redirect URL after authorization. Needs to be url_encoded

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"
}'

{
    "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.

Note: This is only available for BSV transactions

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

Merchant API

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

Examine current Mempool mining pool miner fees
Check the status of BSV transactions
Send transactions directly to Mempool for propagation

Query Mempool miner fees

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

curl --location --request GET 'https://www.ddpurse.com/openapi/mapi/feeQuote'

{
  "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://www.ddpurse.com/platform/openapi/mapi/feeQuote

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://www.ddpurse.com/openapi/mapi/tx/594aa632facc2bdbce31ee02f7865997c0fa17a3360acb2f621cb117ad25c277'

{
  "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://www.ddpurse.com/platform/openapi/mapi/tx/{hash}

Request Path Params

Param	Type	Required	Description
hash	string	YES	The transaction hash

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://www.ddpurse.com/openapi/mapi/tx'
-H 'Content-Type: application/json' \
--data-raw '{
    "rawtx":"020000000111f4be4399b8f466ba2788a6398caa4bf901d04003c653e78b6bb18da2bf9940000000006b483045022100ecdd8c9b34a8a8b10478b8a2bb06af18f294bffd19784bc68b58cba41a70165b022054679dad5e210236321eb09156beab18ea152fb76a97ced3ed418c85fad4ced9412102877b34ce9d3c57813e5730ee41fdc387f4a0f1fa23280774433c415d8e812bd5ffffffff0258020000000000001976a9147499270faa0ca65be4329ad2e1afa71869d1470e88ac15900300000000001976a9142d42015fe20db9eea5694f850fddf2729989fa6388ac00000000"
}'

{
  "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://www.ddpurse.com/platform/openapi/mapi/tx

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>"
    }'

{
  "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>"
    }'

{
  "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>"
}'

{
  "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>"
}'

{
  "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>"
    }'

{
  "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" \

{
  "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-transaction_hash>"
    }'

{
  "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
TransactionHash	string	Yes	Transaction hash

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-transaction_hash>",
        "version": "<YOUR-response version>",
    }'

{
  "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
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

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

Intro

Why use the DotWallet for Developers APIs

Login

Payments

Automatic payment

Blockchain data storage

Inspect the blockchain

Getting Started

Get developer keys

Add ‘login with DotWallet’ to your app

The login button

Note for local development

Get code and compare state

Get user access token (from backend)

Add a payment button

Create order and send to backend

Get API access token (from backend)

Send order to DotWallet (from backend)

Schema

Protocol

HTTP Request

HTTP Response

Authentication

Security

Rate Limits

Authorization

Application Authorization

User Authorization

API Reference

User Info

Get User Info

Transactions

Single Payment Order

Query Order Status

Automatic Payments

Automatic payment flow

Handle insufficient balance

Query user's automatic payment wallet balance

Save Data On Chain or Run Scripts

Badge

Merchant API

Query Mempool miner fees

Query transaction status

Send transaction Rawtx

Blockchain Queries

Block Header

Block Info from Hash

Block Info from Height

Block Info Batch Query from Height

Block Transaction List

Blockchain Basic Info

Transaction inquiry

Merkle branch inquiry

Errors

Contact

Get `code` and compare `state`