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.

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

We can 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 blockchain 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;

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

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?

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:

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"

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

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

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.

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.
autopay.{badge_code}	Badge automatic payments permission. If activated you can make payments and deductions on the user's behalf. eg.`autopay.9bbe61bede9868a194a3568b88f4d504cb9de7aca407adf7d1ad9bf867373914`

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>

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

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

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

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

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

Public and private key generation uses asymmetric encryption elliptic curve algorithm secp256k1, which is the public and private key algorithm used in Bitcoin.
Pubkey must be a compressed public key

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.

Rate Queries

Disclaimer: The exchange rate data comes from mainstream exchanges. Our company shall not be liable for any disputes caused by exchange rate fluctuations and accuracy. Please investigate and decide by yourself before using the service.

get current rate

curl https://api.ddpurse.com/alchemist/authed_public/get_rate

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "CNY": 100000000,
        "USD": 637400000,
        "JPY": 5636050,
        "USDT": 622500000,
        "BTC": 34982912625000,
        "BSV": 91404787500,
        "BCH": 345677362500,
        "ETH": 2792911612500,
        "EOS": 2448697125,
        "timestamp": 1638500865
    }
}

HTTP Request

https://api.ddpurse.com/alchemist/authed_public/get_rate

Request Header

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

Response Body

Param	Type	Description
CNY	int	Value used to calculate rate, see examples as below
USD	int	Value used to calculate rate, see examples as below
JPY	int	Value used to calculate rate, see examples as below
USDT	int	Value used to calculate rate, see examples as below
BTC	int	Value used to calculate rate, see examples as below
BSV	int	Value used to calculate rate, see examples as below
BCH	int	Value used to calculate rate, see examples as below
ETH	int	Value used to calculate rate, see examples as below
EOS	int	Value used to calculate rate, see examples as below
timestamp	int	unix timestamp

if you got result: json { "code": 0, "msg": "", "data": { "CNY": 100000000, "USD": 637400000, "JPY": 5636050, "USDT": 622500000, "BTC": 34982912625000, "BSV": 91404787500, "BCH": 345677362500, "ETH": 2792911612500, "EOS": 2448697125, "timestamp": 1638500865 } } it mean that 1 bsv equals to 146.835(91404787500/622500000) usdt or 914.047875(91404787500 / 100000000) Yuan

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 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, 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，this content is displayed in the "Notes" field in the transaction details of DotWallet
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

Note:
In to[*].type, script is only supported for BSV transactions. BTC, ETH only support address type transactions.
For Badges transactions, use address or user_primary_web for to[*].type.
Paymail transaction supports at most one paymail recipient and one script recipient, where the script receiver amount is fixed at 0, and content starts with 006a.
script receiver type, only BSV transaction support, and if amount is 0, content must start with 006a.

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

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

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

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
badge_code	string	NO	Badge code. Including this code marks this transaction as a Badges transaction
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	Order label or description，this content is displayed in the "Notes" field in the transaction details of DotWallet
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

Note:
In to[*].type, script is only supported for BSV transactions. BTC, ETH only support address type transactions.
For Badges transactions, use address or user_primary_web for to[*].type.
Paymail transaction supports at most one paymail recipient and one script recipient, where the script receiver amount is fixed at 0, and content starts with 006a.
script receiver type, only BSV transaction support, and if amount is 0, content must start with 006a.

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>&redirect_url=<YOUR_REDIRECT_URL>

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
badge_code	string	NO	Badge code

Response Body

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

Order Query

Query Order Status

Support query order payment and automatic payment orders

# 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

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

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

Note: Receiver must be DotWallet account

# 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, `0`for both outgoing and incoming，`1`only incoming transactions，`2`outgoing
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 Merchant API lets developers:

Examine fees
Check the transactions status
Send transactions for propagation

Query fees

Get the latest fee rates.

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

Webot

Get badge balance by address

curl --location --request POST 'https://api.ddpurse.com/v1/bsv/get_badge_balance_by_address' \
--header 'Authorization: Bearer <USER-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "badge_code":"<BADGE-CODE>",
    "addresses":["<ADDRESS>","<ADDRESS>"]
}'

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "balance": 63244
    }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsv/get_badge_balance_by_address

Request Header

http://192.168.1.13:8090/api/v1/users/*

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

Request Body

Parameter	Type	Required	Description
badge_code	string	Yes	badge id
addresses	[]string	Yes	address array

Response Body

Parameter	Type	Description
balance	int	balance

Get badge history by address

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

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {
                "txid": "cb616124609644b197f667810eba17f22991805f8b4fd4871bb2e3110db793a4",
                "amount": 30000
            },
            {
                "txid": "27b3e152ff31be2f6a97f9b20816d4897f6fa1446a0ee19746866326f2dc9cc4",
                "amount": -23
            }
        ],
        "total": 2
    }
}

HTTP Request

POST https://api.ddpurse.com/v1/bsv/get_badge_history_by_address

Request Header

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

Request Body

Parameter	Type	Required	Description
badge_code	string	Yes	badge id
address	string	Yes	address
offset	int	Yes	default 0
limit	int	Yes	default 20

Response Body

Parameter	Type	Description
+list	[]object	history list
└ txid	string	transaction id
└ amount	int	amount
total	int	total count

Create unsigned insufficient fee transaction

curl --location --request POST 'https://api.ddpurse.com/v1/bsv/create_unsign_insufficient_fee_tx' \
--header 'Authorization: Bearer <USER-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from":["<PUBKEY>","<PUBKEY>"],
    "to":[{"address":"<ADDRESS>","amount":"<AMOUNT>"}],
    "badge_code":"<BADGE-CODE>",
    "change_address":"<CHANGE-ADDRESS>"
}'

The above command returns JSON structured like this:

{
    "code": 0,
    "msg": "",
    "data": "0200000001c49cdcf22663864697e10e6a44a16f7f89d41608b2f9976a2fbe31ff52e1b3270100000000ffffffff027803000000000000535101400100015101b101b261146edab19d5b36339361fe674450ec00a513cb3343005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a0821000000000000007803000000000000535101400100015101b101b26114582e39b66ce249ee5c69c42da33fe4b62d2a095e005179517a7561587905626164676587695979a9517987695a795a79ac77777777777777777777776a08bb8100000000000000000000"
}

HTTP Request

POST https://api.ddpurse.com/v1/bsv/create_unsign_insufficient_fee_tx

Request Header

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

Request Body

Parameter	Type	Required	Description
from	[]string	Yes	pubkey from sender
to	[]object	Yes	Receiver Address and Amount
└ address	string	Yes	Receiver address
└ amount	int	Yes	receive amount
badge_code	string	Yes	badge id
change_address	string	Yes	change address

Response Body

Parameter	Type	Description
data	string	unsigned rawTx

法币订单

创建法币订单

# 每次请求，提交正确的header（shell例子）：
curl --location --request POST 'https://api.ddpurse.com/ikki/user_all/create_fiat_order' \
-H "Authorization: Bearer <ACCESS-TOKEN>"
--header 'Content-Type: application/json' \
--data-raw '{
    "request_id": "6666666666666666",
    "currency_amount_bp":"10000000000", 
    "currency_code": "cny", 
    "notify_url": "https://", 
    "redirect_uri": "https://", 
    "info": "备注" 
}'

请求回返是 JSON，例：

{
  "code": 0,
  "msg": "",
  "data": {
      "order_sn": "afec21c2ac724fccda997ff638a08ac2", 
  }
}

HTTP Request

POST https://api.ddpurse.com/ikki/user_all/create_fiat_order

Request Header

参数名	类型	是否必须	说明
Authorization	string	是	Authorization: Bearer ACCESS-TOKEN

Request Body

参数名	是否必须	类型	说明
request_id	是	string	商家订单号，查询时使用
currency_amount_bp	是	string	法币金额,精确到元后面4位数, 例如十元二角五分为 102500
currency_code	是	string	法币类型, cny、usd、eur、gbp
notify_url	否	string	支付结果通知地址，以https://作为前缀，如 https://www.example.com/notify，
redirect_uri	是	string	支付完成后跳转地址，以https://作为前缀，如 https://www.example.com/redirect_uri
info	是	string	订单的备注信息

Response Body

参数名	类型	说明
order_sn	string	订单号

获取订单信息

# 每次请求，提交正确的header（shell例子）：
curl --location --request POST 'https://api.ddpurse.com/ikki/user_all/get_fiat_order' \
-H "Authorization: Bearer <ACCESS-TOKEN>"
--header 'Content-Type: application/json' \
--data-raw '{
    "request_id": "6666666666666666"
}'

请求回返是 JSON，例：

{
  "code": 0,
  "msg": "",
  "data": {
      "order_sn":"xxx",
      "request_id":"xxx",
      "status":1
  }
}

HTTP Request

POST https://api.ddpurse.com/ikki/user_all/get_fiat_order

Request Header

参数名	类型	是否必须	说明
Authorization	string	是	Authorization: Bearer ACCESS-TOKEN

Request Body

参数名	是否必须	类型	说明
request_id	是	string	商家订单号，查询时使用

Response Body

参数名	类型	说明
status	int	账单状态，0 待发布，1 待支付，2 关闭中， 3 数字货币部分到账，4 数字货币已到账, 9 法币到账，-1订单关闭， -2 超时关闭，-9 已删除
request_id	string	商家订单号
order_sn	string	订单号

Badge NFT

NFT integration for developer's wallets

Developers can use their own wallets to perform actions such as minting, transferring and burning an NFT. Users of developer applications are not required to switch to DotWallet. All the NFTs will be transferred among developers' own sub wallets. To create corresponding wallets for each developer application user, developers can bind users to the user_index wallets of their wallet, thus managing the assets of different developer application users. When using a user_index wallet to perform actions such as minting, transferring, burning or receiving addresses, a user_index wallet will be created if such user_index wallet doesn't exist. All the miner fees for minting, transferring and burning will be deducted from the user_index=0 wallet in such situations.

Minting NFTs

curl example:

curl https://api.ddpurse.com/phoenix/user_all/makao_mint_nft

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_mint_nft' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name":"",
    "nft_owner_user_index":123,
    "pics":[
        {
            "pic":""
        }
    ],
    "desc":"",
    "count":50,

}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_mint_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
name	string	NFT names
nft_owner_user_index	int	User's corresponding user_index wallet
pics.pic	object[]	Image url
desc	string	NFT description
count	int	NFT copies (e.g. 10: copy numbers range from 1 to 10, 10 total copies)

Response Body

Param	Type	Description
fee	int64	Minting fees
fee_str	string	Minting fees, string format
fee_coin_type	string	Token type for fees
txid	string	TXID of minting transaction
work_info	object	NftWorkGroupInfo

Bulk minting NFTs

curl example:

curl https://api.ddpurse.com/phoenix/user_all/makao_batch_mint_nft

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_batch_mint_nft' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "nfts":[
      {
        "name":"",
                    "nft_owner_user_index":123,
                           "pics":[
                                {
            "pic":""
                        }
                    ],
                    "desc":"",
                    "count":50,
      },
      {...}
    ]
}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_batch_mint_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
nfts	Array
nfts.name	string	NFT name
nfts.nft_owner_user_index	int	User's corresponding user_index wallet
nfts.pics.pic	string	Image url
nfts.desc	string	NFT description
nfts.count	int	NFT copies (e.g. 10: copy numbers range from 1 to 10, 10 total copies)

Response Body

Param	Type	Description
fee	int64	Minting fees
fee_str	string	Minting fees, string format
fee_coin_type	string	Token type for fees
work_info	object	NftWorkGroupInfo

Transferring NFTs

curl examples:

curl https://api.ddpurse.com/phoenix/user_all/makao_transfer_nft

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_transfer_nft' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from_user_index":123,
    "to_user_index":456,
        "ids":[]
}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_transfer_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
from_user_index	int	user_index of the user whose asset will be transferred away
to_user_index	int	user_index of the user whom the asset will be transferred to
ids	[]string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
fee	int64	Transfer fee
fee_str	string	Transfer fee, string format
txids	[]string	Transaction TXIDs

Sub-wallet NFT transaction history

curl examples:

curl https://api.ddpurse.com/phoenix/nft_intl_get_account_history

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/v1/phoenix/nft_intl_get_account_history' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page":1,
    "page_size":10,
    "user_index":5,
                "transfer_type": "ALL"
}'

HTTP Request

https://api.ddpurse.com/v1/phoenix/nft_intl_get_account_history

Request Header

Parameter	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
page	int	Starts from 1
page_size	int
user_index	int	User's corresponding user_index wallet
transfer_type	string	ALL/income/pay

Response Body

Param	Type	Description
total	int	Total number of records, used for paging
items.id	string	Record ID
items.badge_code	string	NFT badge_code (minting TXID + copy number)
items.created_time	int64	NFT transfer time
items.avatar	string	NFT image url
items.coin	string
items.coin_type	string
items.title	string	NFT title

Obtaining NFT assets of users

curl examples:

curl https://api.ddpurse.com/phoenix/user_all/makao_get_work_group_list

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_get_work_group_list' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page":1,
    "page_size":10,
    "user_index":5,
}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_get_work_group_list

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
page	int	Starts from 1
page_size	int
user_index	int	User's corresponding user_index wallet

Response Body

Param	Type	Description
total	int	Total number
items	NftWorkGroupInfo[]

Definitions of the corresponding structs are shown below: ```

type NftWorkGroupInfo struct { Id string json:"id" Name string json:"name" Cover string json:"cover" Pics []string json:"pics" Desc string json:"desc" CreatedAt int64 json:"created_at" Creator *NftUserInfo json:"creator" PriceRange string json:"price_range" Count *NftCount json:"count" ChainInfo *NftChainInfo json:"chain_info" IsLike bool json:"is_like" LikeNumber int64 json:"like_number" NumberRange string json:"number_range" SingleWorkList []*SingleWork json:"single_work_list" }

type NftUserInfo struct { Id string json:"id" Name string json:"name" Avatar string json:"avatar" Address string json:"address,omitempty" Introduction string json:"introduction,omitempty" Achievements []*Achievement json:"achievements,omitempty" }

type Achievement struct { Id string json:"id" Name string json:"name" Pics []string json:"pics" }

type NftCount struct { Total int64 json:"total" OnShelf int64 json:"on_shelf" OffShelf int64 json:"off_shelf" OnShelfing int64 json:"on_shelfing" Deleted int64 json:"deleted" }

type NftChainInfo struct { Tx string json:"tx" Chain string json:"chain" }

type SingleWork struct { IdIndex string json:"id_index" IndexLabel string json:"index_label" } ```

Obtaining balance

curl example:

curl https://api.ddpurse.com/phoenix/user_all/makao_get_user_balance

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/v1/phoenix/makao_get_user_balance' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_index":0
}'

HTTP Request

https://api.ddpurse.com/v1/phoenix/user_all/makao_get_user_balance

Request Header

Parameter	Type	Required	Description
Authorization	String	Yes	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_index	int	User's corresponding user_index wallet

Response Body

Param	Type	Description
amount	int	BSV balance

Asynchronous bulk minting

HTTP Request https://api.ddpurse.com/phoenix/user_all/makao_batch_mint_nft_async

Request example

{
    "request_id": "",
    "nfts": [
        {
            "name": "",
            "nft_owner_user_index": 0,
            "pics": [
                {
                    "pic": ""
                }
            ],
            "desc": "",
            "count": 0
        }
    ]
}

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

Obtaining results for asynchronous bulk minting

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_get_batch_mint_nft_async_result

{
    "request_id": ""
}

{
    "code": 0,
    "msg": "",
    "data": {
        "results": [
            {
                "fee": 0,
                "fee_str": "",
                "fee_coin_type": "",
                "txid": "",
                "work_info": {
                    "id": "",
                    "name": "",
                    "cover": "",
                    "pics": [
                        ""
                    ],
                    "desc": "",
                    "created_at": 0,
                    "creator": null,
                    "price_range": "",
                    "count": null,
                    "chain_info": null,
                    "is_like": false,
                    "like_number": 0,
                    "number_range": ""
                },
                "state": 0,
                "descript": ""
            }
        ]
    }
}

state 0 Still processing. state 1 Failed. Reason of failure stated in descript. state 2 Success.

Obtaining wallet address

curl example:

curl https://api.ddpurse.com/phoenix/user_all/makao_get_address

The above commands return outputs like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "addr":"xxx"
    }
}

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_get_address

Request Header

Param	Type	Required	Description
Authorization	string	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_index	int	user_index(obtains the address of this sub wallet)

Response Body

Param	Type	Description
addr	string	Main wallet's BSV receive address

Obtaining NFT activities according to badge_code

curl example:

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_get_nft_history' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "page": 1,
    "page_size": 1,
    "id":"ad99409c1ae5d470dcdccafb0d53055da1729772581445d36e0ce16865318d12_1",
}'

The above commands return outputs like this:

{
    "code": 0,
    "msg": "",
    "data": {
        "total": 3,
        "name": "AAA",
        "sn": "#2/2",
        "history": [
            {
                "txid": "8122f33c6bb6f53075dd20f50977b1b181e65d96842056725d68177374a08acc",
                "sender_ucid": "0d158bc3605fffe30f7046f0c9c7e4bf",
                "receiver_ucid": "0d158bc3605fffe30f7046f0c9c7e4bf",
                "send_address": "miHQkTet61zrNS7WqVjEqfH345p6CkVYmN",
                "receive_address": "mx5Ah5Q4VWGSxSPJVKR24jZ6hsvUhVkh9E",
                "timestamp": 1647324886
            }
        ]
    }
}

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_get_nft_history

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
id	string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
total	int	Total number
name	string	Name
sn	string	Copy number
history	array	NFT activities
history.txid	string	TXID
history.sender_ucid	string	Sender UID
history.sender_user_index	int	Sender user_index
history.send_address	string	Sender address
history.receiver_ucid	string	Receiver UID
history.receiver_user_index	int	Receiver user_index
history.receive_address	string	Receiver address
history.timestamp	int	Timestamp

Transferring NFT to third-party address

curl example:

curl https://api.ddpurse.com/phoenix/user_all/makao_transfer_nft_to_address

The above commands return outputs like this:

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_transfer_nft_to_address' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from_user_index":123,
    "to_address":"mvAXXmqBEnq1uuT4CL9mFXLCVEhviakGJw",
        "ids":[]
}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_transfer_nft_to_address

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
from_user_index	int	UID of the user whose asset will be transferred away
to_address	string	Address
ids	[]string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
fee	int64	Transfer fee
fee_str	string	Transfer fee, string format

Obtaining NFT current holder info

Obtaining the user_index wallet of the current holder of an NFT according to NFT badge_code (minting TXID + copy number)

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_get_hold_info
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "badge_code": "bcc39512da2d198de137cf3f6b8a25647c2c96babcb6dd0c3d726dc6e7cf9d96_6"
}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_get_hold_info

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
badge_code	string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
user_index	int	User's corresponding user_index wallet
is_destroy	bool	Burn status

Burning NFTs

Burning NFTs according to NFT badge_code (minting TXID + copy number)

curl --location --request POST 'https://api.ddpurse.com/phoenix/user_all/makao_destroy_nft
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "badge_code": "bcc39512da2d198de137cf3f6b8a25647c2c96babcb6dd0c3d726dc6e7cf9d96_6",
  "user_index": 10
}'

HTTP Request

https://api.ddpurse.com/phoenix/user_all/makao_destroy_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
badge_code	string	NFT badge_code (minting TXID + copy number)
user_index	int	User's corresponding user_index wallet

Response Body

Param	Type	Description
txid	string	Burning TXID

NFT integration for developer applications

Users can connect their wallets to developer applications, where they can perform actions such as minting, transferring, burning NFTs using their wallets.

*Service Introduction: * - 1. There are 3 types of DotWallet users: devleopers, applications and users, all of which can own their own wallets. - 2. Application wallets: Applications can log in to DotWallet Web wallet using app_id or secret - 3. Applications have access only to users' auto-pay wallets (when authorized by users), meaning that NFTs will need to be received with auto-pay wallets.

*Service scenario: * - 1. Applications can perform actions such as minting, transferring and burning NFTs for users (or developers), after an NFT authorization for users' (or developers') auto-pay wallet is agreed. - 2. Applications can also mint the NFTs on its own and then transfer them to developers or users.

Minting NFTs on behalf

curl https://api.ddpurse.com/v1/nft/agent_mint_nft

curl example:

curl --location --request POST 'https://api.ddpurse.com/v1/nft/agent_mint_nft' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id":"",
    "name":"",
    "Desc":"",
    "pics":[{"pic":"", "md5":""}],
    "count":1
    }'

HTTP Request

https://api.ddpurse.com/v1/nft/agent_mint_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_id	string	UID of the user whom is being minted on behalf of
name	string	NFT name
pics.pic	object[]	Image url
desc	string	NFT description
count	int	NFT copies (e.g. 10: copy numbers range from 1 to 10, 10 total copies)

Response Body

Param	Type	Description
fee	int64	Minting fees
fee_str	string	Minting fees, string format
txid	string	NFT TXID (NFT's corresponding badge_code is represented as TXID + "_" + copy number, e.g. dd856320242247da7bb192b0e3501e7b05eb913df51c8e909c35dee7cdf492e8_1)
work_info	object	NFT details

Transferring NFTs on behalf

curl https://api.ddpurse.com/v1/nft/agent_transfer_nft

curl example:

curl --location --request POST 'https://api.ddpurse.com/v1/nft/agent_transfer_nft' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id":""
    "to_address":"",
    "ids":[""],
}'

HTTP Request

https://api.ddpurse.com/v1/nft/agent_transfer_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_id	string	UID of the user whom is being transferred on behalf of
to_address	string	Address that will be transferred to (must be auto-pay wallet address)
ids	[]string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
fee	int64	Transfer fee
fee_str	string	Transfer fee, string format

Burning NFTs on behalf

curl https://api.ddpurse.com/v1/nft/agent_destroy_nft

curl example:

curl --location --request POST 'https://api.ddpurse.com/v1/nft/agent_destroy_nft' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id":"",
    "ids":[""]
}'

HTTP Request

https://api.ddpurse.com/v1/nft/agent_destroy_nft

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_id	string	UID of the user whom is being burned on behalf of
ids	[]string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
txid	string	Transaction TXID

Obtaining NFT activities

curl https://api.ddpurse.com/phoenix/public/get_nft_transaction_history

curl example:

curl --location --request POST 'https://api.ddpurse.com/phoenix/public/get_nft_transaction_history
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "badge_code": "bcc39512da2d198de137cf3f6b8a25647c2c96babcb6dd0c3d726dc6e7cf9d96_6"
}'

HTTP Request

https://api.ddpurse.com/phoenix/public/get_nft_transaction_history

Request Body

Param	Type	Description
badge_code	string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
name	string	NFT name
cover	string	NFT cover
publish_time	int64	Publish time
creator	string	Creator
genesis_transaction	string	Genesis transaction
creator_address	string	Creator
destroy	bool	Burn status
transaction_history.total	int	Total number of activity records
transaction_history.items.txid	string	NFT badge_code (minting TXID + copy number)
transaction_history.items.timestamp	int64	Timestamp
transaction_history.items.from	string	Address from
transaction_history.items.to	string	Address to

Obtaining NFT current holder info

curl https://api.ddpurse.com/phoenix/public/get_badge_owner_info

curl example:

curl --location --request POST 'https://api.ddpurse.com/phoenix/public/get_badge_owner_info
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "badge_code": "bcc39512da2d198de137cf3f6b8a25647c2c96babcb6dd0c3d726dc6e7cf9d96_6"
}'

HTTP Request

https://api.ddpurse.com/phoenix/public/get_badge_owner_info

Request Body

Param	Type	Description
badge_code	string	NFT badge_code (minting TXID + copy number)

Response Body

Param	Type	Description
owner	string	UID of current holder
owner_address	string	Address of current holder
timestamp	int64	Timestamp
destroy	bool	Burn status

Obtaining NFT assets of users

curl https://api.ddpurse.com/v1/nft/query_user_hold_nft_list

curl example:

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

HTTP Request

https://api.ddpurse.com/v1/nft/query_user_hold_nft_list

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_id	string	UID

Response Body

Param	Type	Description
total	int	Total number of records
items.badge_code	string	NFT badge_code (minting TXID + copy number)
items.timestamp	int64	Timestap

Obtaining holder information of NFTs

Checking the holder information of all the NFTs minted by creators using their UCID

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

HTTP Request

https://api.ddpurse.com/v1/nft/query_nft_owner

Request Header

Param	Type	Required	Description
Authorization	String	YES	Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 token

Request Body

Param	Type	Description
user_id	string	UID of creator

Response Body

Param	Type	Description
total	int	Total number of records
items.badge_code	string	NFT badge_code (minting TXID + copy number)
items.owner	string	UID of holder
items.timestamp	int64	Timestamp
items.autopay	bool	Whether using an auto-pay wallet

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.

Go SDK

Import github.com/dotwallet/dotwallet-go-sdk to your project. It's an more convenient way to call the Api provided by DotWallet

This repository include some examples.

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 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: developers@dotwallet.com Telegram: https://t.me/mempool_developer