Intro
Why use the DotWallet for Developers APIs
DotWallet for Developers helps you use Bitcoin SV's blockchain infrastructure more easily.
With the DotWallet for Developers APIs, you can add powerful features to your app.
Apps integrating DotWallet login can be listed on the DotWallet App Store, bringing in tons of new user traffic.
Login
You can create a simple and convenient login and sign up method for your users. DotWallet users can sign up for your app with one click, and non-DotWallet users can instantly sign up for DotWallet through Facebook, Google, WeChat, mobile number or email.
See Authorization and Get User Info for more.
Payments
Traditional apps can only accept payments from users but cannot pay out payments to users. With the DotWallet APIs, you can set up app-user or user-user transactions. You can easily set up advanced payment options like configuring multiple receivers and including transaction data in Bitcoin’s OP_RETURN field.
See Payments for more.
Automatic payment
After prompting the user once to authorize your app and transfer funds into the auto payments wallet, your app will not need the user to manually authorize every payment. Besides being convenient for users, this unlocks new possibilities for micro-transaction based applications and server-to-server use cases. Using DotWallet’s advanced networking technology, micropayments on our API can break through the Bitcoin network’s limit on transactions.
See Automatic Payments for more.
Blockchain data storage
Store your users’ data, or your app’s data in an immutable record on the blockchain, providing user confidence that their important data is backed up. This can be used to prove that certain data was created/received at a certain time and to verify the integrity and veracity of the data. This can be an auditable record that can for example prove the fairness of a prize payout’s conditions.
Data can be saved on-chain using the 'to' object of a payment order. In the 'type' field pass in 'script', then put your data in the 'content' field. You can attach data to user's payments, or set up your own DotWallet and pay for data saving yourself. For details, see Saving Data, Automatic Payments, and Payments.
Inspect the blockchain
As a large player in the Bitcoin mining industry, our Mempool mining pool lets us provide the most detailed and up to date information about the blockchain. Query transactions and blockchain data with our query APIs, and examine the state of Bitcoin mining with our direct connection to the Merchant API.
See Blockchain API for more.
Getting Started
This is a simple guide for developers looking to add dotwallet login and payment features to an app. Examples are in JavaScript. More complete code (which includes error handling) for these examples can be found here.
Get developer keys
First, sign up with DotWallet for Developers to apply for a client ID and client secret key.
Click the “JOIN NOW” button in the top right corner of the DotWallet for Developers homepage. Once you have completed your application, sign in and click on “Applications” in the nav bar and “+Add application” on that page. The client ID and secret will be sent to your provided email.
Add ‘login with DotWallet’ to your app
The login button
Add a simple button to your app’s frontend, and wrap it in an <a>
link that redirects the browser to DotWallet’s authentication screen.
<a id="login-link" >
<img src="src/assets/dotwallet-login.png" alt="dotwallet-login" />
</a>
<!-- You'll need uuid or another random string generator for the next step -->
<!-- <script src="https://unpkg.com/uuid@latest/dist/umd/uuidv4.min.js"></script> -->
const scope = encodeURIComponent('user.info autopay.bsv autopay.btc autopay.eth'); // the permissions we'd like to ask the user for
const redirectURI = encodeURIComponent(`${YOUR_APP_URL}/your-login-landing-page`);
const loginState = uuidv4(); // 'state' should be a random string. used to confirm that the login request was made from the same source and avoid csrf attacks
localStorage.setItem('loginState', loginState); // save the 'state' to compare later
const loginURL = `https://api.ddpurse.com/authorize?client_id=${YOUR_CLIENT_ID}&redirect_uri=${redirectURI}&response_type=code&state=${loginState}&scope=${scope}`; // construct the link
document.getElementById('login-link').href = loginURL;
Download the button image from our UI resources page
Note for local development
You cannot use localhost
as the redirect_uri
For local development, find your machine’s IP by putting the following command into the terminal:
ifconfig | grep netmask
You’ll get a result like this
inet 127.0.0.1 netmask 0xff000000
inet 192.168.1.142 netmask 0xffffff00 broadcast 192.168.1.255
Use 192.168.1.142
+ your PORT number and route as the redirect_uri
, for example http://192.168.1.142:3000/auth/
Login to your DotWallet for Developers account and click on “Applications”. Select your application, then go to “Display Information”, hit the edit button and add your domain to the Callback domain field. Do not add http, so in this case just add 192.168.1.142:3000/auth/
. make sure you hit save, and refresh the page to make sure it saved.
Get code
and compare state
Once the user approves, the browser will be sent to your provided redirect_uri
with a one time code
and the state
as query parameters.
const urlParams = new URLSearchParams(window.location.search);
const state = urlParams.get('state');
const code = urlParams.get('code');
const savedState = localStorage.getItem('loginState');
if (state != savedState) { // if the state is the same as from step 1...
alert('error validating request');
} else {
fetch(`${YOUR_BACKEND_SERVER}/auth`, { // ...then send the code to your backend server
method: 'POST',
body: JSON.stringify({ code }),
headers: {
'Content-type': 'application/json; charset=UTF-8',
},
});
}
Get user access token (from backend)
Warning: This must be done from your backend server. Also remember to use .env files and never upload your client secret to GitHub.
Say we have this simple Express.js server:
const express = require('express');
const axios = require('axios');
const path = require('path');
const dotenv = require('dotenv');
const app = express();
const PORT = process.env.PORT || 3000;
const YOUR_CLIENT_SECRET = process.env.CLIENT_SECRET;
const YOUR_CLIENT_ID = process.env.CLIENT_ID;
const DOTWALLET_API = 'https://api.ddpurse.com/v1'
// ...
// routes logic will go here here
// ...
app.listen(PORT, () =>
console.log(`DotWallet example app listening at PORT: ${PORT}`)
);
Create a POST
endpoint to accept the code.
app.post('/auth', async (req, res) => {
const data = {
client_id: YOUR_CLIENT_ID,
client_secret: YOUR_CLIENT_SECRET,
grant_type: 'authorization_code',
code: code,
redirect_uri: `${YOUR_APP_URL}/your-login-landing-page`, // must be the same url from step one
};
const accessTokenRequest = await axios.post(`${DOTWALLET_API}/oauth2/get_access_token`, data);
const userAccessToken = accessTokenRequest.data.data.access_token
// With our access_token we can look up the user’s profile information.
if (userAccessToken) {
const options = {
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
method: 'POST',
};
const userInfoRequest = await axios(`${DOTWALLET_API}/user/get_user_info`, options);
const userInfo = userInfoRequest.data.data
}
});
Success! You have confirmed the user's identity. Based on the permissions user.info autopay.bsv autopay.btc autopay.eth
, you have been granted permission to their basic profile information, and can perform automatic payments on their behalf.
Add a payment button
Make a simple button:
<button id="banana-button" type="button">546 satoshis</button>
546 satoshis is the minimum payment amount
Create order and send to backend
Handle the button click in the script and make an object with your payment order details. Send the order details to your backend. Your backend will send the order details to the DotWallet API, and will receive an order ID order_sn
back.
document.getElementById('banana-button').addEventListener('click', async () => {
const orderData = {
out_order_id: uuidv4(),
coin_type: 'BSV',
to: [
{
type: 'address',
content: '1L3z6DzHpfr7pkkZmKfVGMjwY1984D5YRv', // REPLACE WITH YOUR WALLET ADDRESS!!!!!!!
amount: 546,
},
],
product: {
id: uuidv4(),
name: 'bananas',
},
notify_url: YOUR_SERVER_URL + '/payment-result',
redirect_uri: window.location.href,
};
const orderSnResponse = await fetch(
YOUR_SERVER_URL + '/create-order',
{
method: 'POST',
body: JSON.stringify(orderData),
headers: {
'Content-type': 'application/json; charset=UTF-8',
},
}
);
const orderSnData = await orderSnResponse.json();
// When our backend returns the order_sn, send the user to confirm the payment
window.location.href = `${DOTWALLET_API}/v1/transact/order/apply_payment?order_id=${orderSnData.order_sn}`;
}
Get API access token (from backend)
Developer/app authentication is a prerequisite for most DotWallet API endpoints. Use your client_secret and client_id to get an auth token.
let appAccessToken = '';
async function getAppAccessToken() {
const data = {
client_id: YOUR_CLIENT_ID,
client_secret: YOUR_CLIENT_SECRET,
grant_type: 'client_credentials',
};
const accessTokenRequest = await axios.post(`${DOTWALLET_API}/oauth2/get_access_token`, data);
appAccessToken = accessTokenRequest.data.data.access_token;
}
Send order to DotWallet (from backend)
This uses your client secret key and must be done from the backend server side.
Set up our Express.js app endpoint to receive the order and send it to DotWallet’s API in return for an order_sn
.
app.post('/create-order', async (req, res) => {
const options = {
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${appAccessToken}`,
},
method: 'POST',
data: { ...orderData },
};
const orderSnResponse = await axios(`${DOTWALLET_API}/transact/order/create`, options);
const orderSn = orderSnResponse.data.data;
res.json({ order_sn: orderSn })
});
That’s it! Your app can now handle login and basic payments.
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 usingJSON
, and the Http headerContent-Type
set toapplication/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 be0
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 a75000
error
HTTP 200
{
"code": 75000,
"msg": "Invalid access token",
"data": null
}
DotWallet will authenticate all Api resource requests. To authenticate simply add the following to each request's HTTP Header:
Authorization: Bearer YOUR-ACCESS-TOKEN
How to get access_token in JWT form
Get application-level access_token
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 thescope
requires the user's consent and authorization
URL Parameters
Parameter | Required | Description |
---|---|---|
client_id | Yes | Developer’s client_id |
redirect_uri | Yes | The redirect URL after authorization. Needs to be url_encoded |
response_type | Yes | Fill in the fixed value : code |
state | Yes | It is recommended to use a random string of more than 32 bits (such as UUID). The state is used to verify the consistency of the request and callback. This can prevent csrf attacks. |
scope | Yes | Authorization scope. The list of permissions that the user agrees to authorize. These permissions are required for certain API endpoints. Needs to be url_encoded. Use spaces to separate multiple permissions. For a list of currently supported scope permissions, please check the scope list below |
scope list
scope | Description |
---|---|
user.info | Get user's basic information |
autopay.bsv | BSV automatic payments permission. If activated you can make payments and deductions on the user's behalf. |
autopay.btc | BTC automatic payments permission. If activated you can make payments and deductions on the user's behalf. |
autopay.eth | ETH automatic payments permission. If activated you can make payments and deductions on the user's behalf. |
Step 2: Redirect the user to the URI constructed in step 1
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: Recieve 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 providedstate
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
API Reference
The following are detailed documentation for all of the currently available API endpoints provided by DotWallet for Developers.
User Info
Get User Info
Through the user information API endpoint, third-party applications can obtain information authorized by DotWallet users.
# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/user/get_user_info' \
-H "Authorization: Bearer <USER-ACCESS-TOKEN>"
The above command returns JSON structured like this:
{
"code": 0,
"msg": "",
"data": {
"id": "1278104675169476608",
"nickname": "hello world",
"avatar": "https://your_avatar",
"web_wallet_address": {
"bsv_regular": "14s59qZEA1m7B8zAAUVMtonWrKfnEdPzxh",
"btc_regular": "18nneDCo7UmhyUjdeupNgkThAsGcc3rAVT",
"eth_regular": "0xc1CD83264a329B4cB319b9FD3fbf16AbD7808FcF"
}
}
}
HTTP Request
POST https://api.ddpurse.com/v1/user/get_user_info
Request Header
Parameter | Type | Required | Description |
---|---|---|---|
Authorization | string | Yes | Authorization: Bearer USER-ACCESS-TOKEN,Grant Type: User Authorization |
Response Body
Parameter | Type | Description |
---|---|---|
id | string | User ID |
nickname | string | User nickanme |
avatar | string | User avatar |
+web_wallet_address | Object | The user's receiving address on the web of DotWallet |
└ bsv_regular | string | The user's BSV receiving address on the web of DotWallet |
└ btc_regular | string | The user's BTC receiving address on the web of DotWallet |
└ eth_regular | string | The user's ETH receiving address on the web of DotWallet |
Transactions
With DotWallet for Developers payment APIs, third parties can quickly integrate powerful payment functions.
When paying, you will guide DotWallet users to log in to the dot wallet application (web app) to complete the transaction.
Single payment orders require the user to manually confirm the each transaction. With Autopayments, the user only needs to authorize once and the application can initiate transactions on their behalf.
Single Payment Order
Step 1:Create an order, submit it to DotWallet, and obtain an
order_id
Step 2:Construct a payment URL and redirect the user to it to confirm payment
Step 3:Receive and handle payment confirmation
Step 1: Create a Payment Order
# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/transact/order/create' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"out_order_id":"0001",
"coin_type":"BSV",
"to":[{
"type":"address",
"content":"mnjV6Fy9ge35xWsqu9rSS4bTG2wxsuoKy7",
"amount":10000000
},
{
"type":"script",
"content":"006a",
"amount":0
}
],
"product":{
"id":"001",
"name":"apple",
"detail":"This is a red apple."
},
"subject":"Red Apple",
"notify_url":"https://test.com",
"redirect_uri":"https://test.com",
"expires":2601452710
}'
HTTP Request
POST https://api.ddpurse.com/v1/transact/order/create
Request Header
Param | Type | Required | Description |
---|---|---|---|
Authorization | string | YES | Authorization: Bearer APP-ACCESS-TOKEN,auth method: Application Auth |
Request Body
Param | Type | Required | Description |
---|---|---|---|
out_order_id | string | YES | Client defined order number. Recommend 32 digit random UUID string |
coin_type | string | YES | Payment coin type. Currently supported: BTC, BSV, ETH |
+to | object[] | YES | An array of transaction objects. |
└ type | string | YES | Receiver type, must be address orscript |
└ content | string | YES | Receiver address or script content. If type is address , this should be a valid address. if type is script ,This should be a hex script. script is only supported for BSV |
└ amount | int | YES | Transaction amount. Unit: satoshi (BSV, BTC) or gwei (ETH). Minimum amount: 546 satoshi (BSV, BTC) for address transactions. script and ETH transactions have no minimum. |
+product | object | YES | Product information object |
└ id | string | YES | Product ID/SN |
└ name | string | YES | Product name |
└ detail | string | NO | Product description |
badge_code | string | NO | Badge code. Including this code marks this transaction as a Badges transaction |
subject | string | NO | Order label or description |
notify_url | string | NO | Address to send payment result notification to |
redirect_uri | string | NO | Address to redirect browser to after payment completion |
expires | int | NO | Order expiry time. Unix epoch time in seconds. Leave this blank or submit 0 and the order will not expire |
- Note:
- In
to[*].type
,script
is only supported for BSV transactions. BTC, ETH only supportaddress
type transactions. - For Badges transactions, use
address
forto[*].type
andto[*].content
must be a valid DotWallet user address.
Response Body
{
"code": 0,
"msg": "",
"data": "1318817847320780800"
}
Param | Type | Description |
---|---|---|
data | string | Order ID (order_id ) |
Step 2:Construct payment URL, redirect user
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}
The user will be redirected to the payment page of the DotWallet web app after clicking the link. It may require the user to log in, and then perform the payment operation.
Step3:Receive payment result
After the user completes the payment you can be notified of the payment result. The result is sent in JSON format with a POST
request to your provided notify_url
.
Notify Request Body
Param | Type | Description |
---|---|---|
order_id | string | Order ID |
out_order_id | string | Client defined order ID |
user_id | string | User ID of the payer |
amount | int | Payment amount. Unit: satoshi(BSV, BTC) or gwei (ETH) |
fee | int | miner fee. Unit: satoshi(BSV, BTC) or gwei (ETH) |
txid | string | Transaction ID |
Query Order Status
# With shell, you can just pass the correct header with each request
curl --location --request GET 'https://api.ddpurse.com/v1/transact/order/get_order' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"order_id":"1306515412057333760"
}'
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 |
└ blockheight | int | Transaction block height. -1 means not yet included in a block |
└ time | int | Time that transaction was included in a block. Unix epoch time in seconds |
└ confirmation | int | Confirmations. -1 means not yet included in a block |
└ fee | int | Transaction miner fee |
└ txid | string | Transaction ID |
└ +vins | object[] | Transaction inputs |
└ └ address | string | Address |
└ └ amount | string | Amount |
└ └ index | string | Vins order index |
└ +vouts | object[] | Transaction outputs |
└ └ address | string | Address |
└ └ amount | string | Amount |
└ └ index | string | Vouts order index |
Automatic Payments
Automatic payment allows apps that have received User authorization to make automatic payments on behalf of a DotWallet user. The user will only need to be prompted once, after which the app can make payments with the users funds up to the wallet balance.
Use cases
It is suitable for high frequency payments and to avoid users having to jump to the payment confirmation page all the time. This is useful in lotteries, repeated payments, games, and social media, or for allowing third-party applications to pay utility bills on behalf of the user.
Automatic payment flow
- Step 1:Redirect DotWallet user to the authorization page to obtain user authorization and make sure to add the
scope
for auto payments related permissions
Step 2:Obtain
access_token
through user authorization and call the Get User Information API endpoint to get the user ID. Save the authorized user ID for subsequent useStep 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 |
user_id | string | Yes | DotWallet User ID |
+to | object[] | YES | An array of transaction objects. |
└ type | string | YES | Receiver type, must be address orscript |
└ content | string | YES | Receiver address or script content. If type is address , this should be a valid address. if type is script ,This should be a hex script. script is only supported for BSV |
└ amount | int | YES | Transaction amount. Unit: satoshi (BSV, BTC) or gwei (ETH). Minimum amount: 546 satoshi (BSV, BTC) for address transactions. script and ETH transactions have no minimum. |
+product | object | YES | Product information object |
└ id | string | YES | Product ID/SN |
└ name | string | YES | Product name |
└ detail | string | NO | Product description |
subject | string | NO | Order label or description |
notify_url | string | NO | Address to send payment result notification to |
- Note: BTC, ETH only support
address
transactions, notscript
.to[*].type
must beaddress
。
Response Body
Param | Type | Description |
---|---|---|
order_id | string | Order ID |
out_order_id | string | Client defined order ID |
user_id | string | User ID of the payer |
amount | int | Payment amount. Unit: satoshi(BSV, BTC) or gwei (ETH) |
fee | int | miner fee. Unit: satoshi(BSV, BTC) or gwei (ETH) |
txid | string | Transaction ID |
After the user completes the payment, the payment result info will be to sent in JSON format to notify_url
in a POST
request.
Notify Request Body
Param | Type | Description |
---|---|---|
order_id | string | Order ID |
out_order_id | string | Client defined order ID |
user_id | string | User ID of the payer |
amount | int | Payment amount. Unit: satoshi(BSV, BTC) or gwei (ETH) |
fee | int | miner fee. Unit: satoshi(BSV, BTC) or gwei (ETH) |
txid | string | Transaction ID |
After the transaction is completed, DotWallet will send up to 15 notifications within the next 24 hours. After you have successfully received a notification, please respond to the POST request with the following info to confirm you've received the notification and cancel the subsequent notifications.
Notify Response Body
Parameter | Type | Description |
---|---|---|
code | int | status code,0 :success |
Example response:
{
"code": 0,
}
Handle insufficient balance
If the payment request from the previous step returns an error with the code
10180007 then the user's autopay wallet balance too low. A code
of 10180029 means the user's designated transaction limit is too low. In these cases you should redirect the user to change the settings or move funds into their autopay wallet.
Redirect the user to this URL:
https://ddpurse.com/wallet/open/transfer?redirect_url=<YOUR_REDIRECT_URL>
URL Parameters
Parameter | Required | Description |
---|---|---|
redirect_url | NO | The redirect URL after authorization. Needs to be url_encoded |
Query user's automatic payment wallet balance
# With shell, you can just pass the correct header with each request
curl --location --request POST 'https://api.ddpurse.com/v1/user/get_autopay_balance' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"coin_type": "BSV",
"user_id": "6a1b2161094e32bf2c352910218048da"
}'
The above command returns JSON structured like this:
{
"code": 0,
"msg": "",
"data": {
"confirm": 85613,
"unconfirm": 0
}
}
HTTP Request
POST https://api.ddpurse.com/v1/user/get_autopay_balance
Request Header
Parameter | Type | Required | Description |
---|---|---|---|
Authorization | String | YES | Authorization: Bearer APP-ACCESS-TOKEN , Oauth2 clients credentials grant |
Request Body
Parameter | Type | Required | Description |
---|---|---|---|
coin_type | string | Yes | The currency to be queried, supports BTC, BSV, ETH |
user_id | string | Yes | User ID to be queried |
Response Body
参数名 | 类型 | 说明 |
---|---|---|
confirm | int | Confirmed balance |
unconfirm | int | Unconfirmed balance |
Save Data On Chain or Run Scripts
Save data or a script onto the blockchain by using the Payment Order API or the Automatic Payment API. Please see the links for how to use these APIs.
https://api.ddpurse.com/v1/transact/order/autopay
or
https://api.ddpurse.com/v1/transact/order/create
In the to
parameter object array, pass in script
for type
, and pass in the data for content
.
- Note: This is only available for BSV transactions
Use cases
This can be used to verify or store various records and data. Saving data on chain can be used to improve the longevity of data. It can be used along with timestamps to prove that a certain data transaction happened at a certain time. For large data sets, it is sometimes better to just save a hash of the data on chain. The hash can be later be compared to the data to verify that the data has not been modified.
Data/script Format
Make sure your data/script is a hex encoded string. Prefix the data with 006a
# Saving data with automatic payment:
curl --location --request POST 'https://api.ddpurse.com/v1/transact/order/autopay' \
--header 'Authorization: Bearer <APP-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"out_order_id":"0001",
"coin_type":"BSV",
"user_id":"6a1b2161094e32bf2c35298048da",
"to":[{
"type":"script",
"content":"006a<YOUR HEX ENCODED DATA HERE>",
"amount":0
}],
"product":{
"id":"001",
"name":"data",
"detail":"This is some important data."
},
"notify_url":"https://www.example.com/"
}'
// Saving data with automatic payment:
async function saveDataWithAutopayment(DATA, YOUR_APP_ACCESS_TOKEN) {
const hexEncoded = Buffer.from(JSON.stringify(DATA), 'utf8').toString('hex');
const orderData = {
user_id: '',
out_order_id: uuidv4(),
coin_type: 'BSV',
to: [
{
type: 'script',
content: `006a${hexEncoded}`,
amount: 0,
},
],
product: {
id: uuidv4(),
},
notify_url:'https://www.example.com/'
};
const options = {
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${YOUR_APP_ACCESS_TOKEN}`,
},
method: 'POST',
data: orderData,
};
const response = await axios(`https://api.ddpurse.com/v1/transact/order/autopay`, options);
const txid = response.data.data.txid;
return txid;
}
You will receive back the transaction information. It will also be sent to your notify_url. Please store the transaction ID (txid) in order to retrieve the data later.
Retrieving Data
You can use our Transaction Query API to find the transaction including your data. Check the link for usage details.
https://api.ddpurse.com/v1/bsvchain/get_transaction
In the response object, your data will be in the vouts
array. Usually, the transaction with your data will be the first object in the array (index 0). To confirm, you can look at each object in the array and examine the script_hex
property. The one that starts with 006a
will be your data.
Remember to remove the 006a
and decode your data from hex.
async function getData(YOUR_APP_ACCESS_TOKEN, TXID) {
const options = {
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${YOUR_APP_ACCESS_TOKEN}`,
},
method: 'POST',
data: JSON.stringify({ transaction_hash: TXID }),
};
const response = await axios('https://api.ddpurse.com/v1/bsvchain/get_transaction', options);
const responseData = response.data;
let data;
responseData.data.vouts.forEach((vout) => {
if (vout.script_hex.startsWith('006a')) {
const hexDecoded = Buffer.from(
vout.script_hex.slice(4), // slice off the '006a'
'hex'
).toString('utf8');
data = JSON.parse(hexDecoded);
}
});
return data;
}
Badge
Merchant API
This API connects developers to the BSV Merchant API and lets developers:
- Examine current Mempool mining pool miner fees
- Check the status of BSV transactions
- Send transactions directly to Mempool for propagation
Query Mempool miner fees
Get the latest miner fees (Bitcoin transaction fee rates) from the Mempool mining pool.
curl --location --request GET 'https://www.ddpurse.com/openapi/mapi/feeQuote'
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://www.ddpurse.com/platform/openapi/mapi/feeQuote
Response Body
Param | Type | Description |
---|---|---|
payload | string | main data payload encoded in a specific format type |
signature | string | signature on payload string. This may be null. |
publicKey | string | public key to verify signature. This may be null. |
encoding | string | encoding type |
mimetype | string | Multipurpose Internet Mail Extensions type |
Payload
Param | Type | Description |
---|---|---|
apiVersion | string | version of merchant api spec |
timestamp | string | timestamp of payload document |
expiryTime | string | expiry time of quote |
minerId | string | minerID / public key of miner. This may be null. |
currentHighestBlockHash | string | hash of current blockchain tip |
currentHighestBlockHeight | int | hash of current blockchain tip |
minerReputation | string | reputation of miner |
fees | object[] | fees charged by miner (feeSpec BRFC) |
Query transaction status
curl --location --request GET 'https://www.ddpurse.com/openapi/mapi/tx/594aa632facc2bdbce31ee02f7865997c0fa17a3360acb2f621cb117ad25c277'
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://www.ddpurse.com/platform/openapi/mapi/tx/{hash}
Request Path Params
Param | Type | Required | Description |
---|---|---|---|
hash | string | YES | The transaction hash |
Response Body
Param | Type | Description |
---|---|---|
payload | string | main data payload encoded in a specific format type |
signature | string | signature on payload string. This may be null. |
publicKey | string | public key to verify signature. This may be null. |
encoding | string | encoding type |
mimetype | string | Multipurpose Internet Mail Extensions type |
Payload
Param | Type | Description |
---|---|---|
apiVersion | string | version of merchant api spec |
timestamp | string | timestamp of payload document |
returnResult | string | will contain either success or failure |
resultDescription | string | will contain the error on failure or empty on success |
blockHash | string | hash of tx block |
blockHeight | int | hash of tx block |
minerId | string | minerId public key of miner |
confirmations | int | number of block confirmations |
txSecondMempoolExpiry | int | Duration (minutes) Tx will be kept in secondary mempool |
Send transaction Rawtx
curl --location --request POST 'https://www.ddpurse.com/openapi/mapi/tx'
-H 'Content-Type: application/json' \
--data-raw '{
"rawtx":"020000000111f4be4399b8f466ba2788a6398caa4bf901d04003c653e78b6bb18da2bf9940000000006b483045022100ecdd8c9b34a8a8b10478b8a2bb06af18f294bffd19784bc68b58cba41a70165b022054679dad5e210236321eb09156beab18ea152fb76a97ced3ed418c85fad4ced9412102877b34ce9d3c57813e5730ee41fdc387f4a0f1fa23280774433c415d8e812bd5ffffffff0258020000000000001976a9147499270faa0ca65be4329ad2e1afa71869d1470e88ac15900300000000001976a9142d42015fe20db9eea5694f850fddf2729989fa6388ac00000000"
}'
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://www.ddpurse.com/platform/openapi/mapi/tx
Request Body
Param | Type | Required | Description |
---|---|---|---|
rawtx | string | YES | Transaction raw hex |
Response Body
Param | Type | Description |
---|---|---|
payload | string | main data payload encoded in a specific format type |
signature | string | signature on payload string. This may be null. |
publicKey | string | public key to verify signature. This may be null. |
encoding | string | encoding type |
mimetype | string | Multipurpose Internet Mail Extensions type |
Payload
Param | Type | Description |
---|---|---|
apiVersion | string | version of merchant api spec |
timestamp | string | timestamp of payload document |
txid | string | transaction ID |
returnResult | string | will contain either success or failure |
resultDescription | string | will contain the error on failure or empty on success |
minerId | string | minerId public key of miner |
currentHighestBlockHash | string | hash of current blockchain tip |
currentHighestBlockHeight | int | hash of current blockchain tip |
txSecondMempoolExpiry | int | Duration (minutes) Tx will be kept in secondary mempool |
Please see the official Merchant API Github for details:https://github.com/bitcoin-sv-specs/brfc-merchantapi
Blockchain Queries
Block Header
Get the raw block header using the block hash
curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_raw_block_header' \
-H'Content-Type: application/json' \
-H "Authorization: Bearer APP-ACCESS-TOKEN" \
-d'{
"blockhash": "<YOUR-blockhash>"
}'
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-transaction_hash>"
}'
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 |
---|---|---|---|
TransactionHash | string | Yes | Transaction hash |
Response Body
Param | Type | Description |
---|---|---|
vouts | json | all vout |
vins | json | all vin |
index | int | index of vin or vout |
confirmation | int | confirmation number |
timestamp | int | timestamp |
size | int | Transaction size (unit: byte) |
value | int | Transaction amount (unit: satoshi) |
script | string | Hex coded script |
txid | string | txid of the transaction |
height | int | Block height, -1 means unconfirmed |
Merkle branch inquiry
Query merkle branch through txid
curl -X POST'https://api.ddpurse.com/v1/bsvchain/get_standard_merkle' \
-H'Content-Type: application/json' \
-H "Authorization: Bearer APP-ACCESS-TOKEN" \
-d'{
"txid": "<YOUR-transaction_hash>",
"version": "<YOUR-response version>",
}'
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 |
version | string | Yes | response version:"0","1"... |
Response Body
Param | Type | Description |
---|---|---|
version | string | the version you set in the request |
path | string[] | merkle branches |
index | int | the index of the transaction in the block |
header | byte[] | block header bytes |
Errors
HTTP status codes that DotWallet Api may return:
HTTP Status | Description |
---|---|
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
502 | Bad Gateway |
503 | Service Unavailable |
504 | Gateway Timeout |
DotWallet Api may return code
business error codes:
code | Description |
---|---|
75000 | Invalid access token |
Contact
You can contact DotWallet for support in the following ways: Email: business@boquaninc.com Telegram: https://t.me/mempool_developer