API how to: Open an account & Transact in Bitcoin

Our mission is to provide modern financial services and enable anybody to do the same.

While the eminent launch of our beta BVNK platform is gearing up, our library of APIs is ready to use and aimed at the developer and entrepreneurial community. We encourage developers to use our API on our demo instance; no API key is required so you can get started right away.

Here’s a primer on creating a user account and opening a Bitcoin transactional account.

Sign up

First things first, you need to sign up as a user.

A user acts as an account holder; all accounts need to be linked to a given user. In addition, a user is a necessity for Know Your Customer requirements. AccountHolderCountry must be a valid ISO2 code. Valid countries and their codes can be retrieved through GET /countries .

POST https://demo.bvnk.co/account/signup

Note: this call requires HTTP basic authentication. You can find those details in the introduction of our API documentation.

curl -X POST \
https://demo.bvnk.co/account/signup \
-H 'Authorization: Basic YnZuazpldml0YWJsZS1jYXVjdXMtZm9yZXNhdy1wcmVzc21hbi1mbGF0Y2FyLWZpZXJ5LW9mZnNob290LWhvdXI=' \
-H 'Cache-Control: no-cache' \
-H 'Postman-Token: a7d75f11-876a-9458-b195-43c967d62111' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F AccountHolderGivenName=Debug \
-F AccountHolderFamilyName=Account \
-F AccountHolderDateOfBirth=1900-01-01 \
-F AccountHolderIdentificationNumber=400000-0000-001 \
-F 'AccountHolderContactNumber1=(558) 555-42381' \
-F AccountHolderEmailAddress=alice@bankai.co \
-F 'AccountHolderAddressLine1=Address 1' \
-F 'AccountHolderAddressLine2=Address 2' \
-F 'AccountHolderAddressLine3=Address 3' \
-F AccountHolderPassword=password \
-F AccountHolderPostalCode=1234 \
-F AccountHolderCountry=GB

A successful response will return a uuid that will be required in subsequent auth requests.

Successful response:

{
"response": "7217123a-c4e5-440f-a7b9-94230d303d66"
}

Error response:

{
"error": "Contact number already linked to another user"
}

Authentication

To avoid sending AccountHolderIdentificationNumber on all auth requests, an immutable uuid is created using this endpoint.

POST https://demo.bvnk.co/auth/account

Note: the saved uuid will be returned if authorisation for the user has been created before.

curl -X POST \
https://demo.bvnk.co/auth/account \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'postman-token: d9cec22a-f367-31ed-99bb-a725767cc5db' \
-F UserIdentificationNumber=300000-0000-001 \
-F Password=test1234

Successful response:

{
"response": "3069ecbc-bf37-421d-a66f-6b78d56fd86f"
}

Error response:

{
"error": "Password must be at least 8 characters"
}

Log In

We then use the uuid returned in the previous step, and Password (this is created in the first step, AccountHolderPassword) to log in. An auth token is returned.

POST https://demo.bvnk.co/auth/login

Note: the User value is the uuid from the previous step.

curl -X POST \
https://demo.bvnk.co/auth/login \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'postman-token: 0d828327-c0f7-f4b4-2af5-45139ff6ec6f' \
-F User=3069ecbc-bf37-421d-a66f-6b78d56fd86f \
-F Password=test1234

Successful response:

{
"response": "6836d1f3-2321-45eb-9173-efeaa211a6d5"
}

Error response:

{
"error": "Authentication credentials invalid"
}

Create Transactional Account

Once a user has been created, we can open up a currency account linked to it. Right now, we only support BTC (Bitcoin) in production and BCT (Bitcoin Testnet) on our demo instance, but we are adding multiple cryptocurrencies over the next couple of months. Once we have obtained the correct licenses in specific territories, we will introduce fiat currencies too. All currencies will have the same account structure; we treat cryptocurrencies as any other currency.

POST https://demo.bvnk.co/account

Note: supported currencies can be retrieved through GET /currencies .

curl -X POST \
https://demo.bvnk.co/account \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: b32bfcc5-d0c6-07bf-b833-9cd815c21980' \
-H 'X-Auth-Token: ee2cd9fb-a165-40c7-95af-c05d4d5f8117' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F AccountCurrency=bct \
-F AccountType=cheque

Successful response:

{
"response": "9e7d08ef-5377-4ebc-a606-186dbe07020e"
}

Error response:

{
"error": "Account type not valid, must be one of savings, cheque, merchant, money-market, cd, ira, rcp, credit, mortgage, loan"
}

It’s advisable to create a second account in order to test transactions.

Getting Account Details

To test transactions, we need to fund the accounts with BCT, and to do that we need retrieve the WalletAddress.

GET https://demo.bvnk.co/account/all

Note: wallet addresses are not static and change when ever funds are received to that address. This is a core feature of Bitcoin, and promotes anonymity and security in our system.

curl -X GET \
https://demo.bvnk.co/account/all \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: f1858b57-6bab-cf56-ba54-4044e4260481' \
-H 'X-Auth-Token: 8400a09e-7676-4aa3-bce0-57a216b7f1b0'

Successful response:

{
"response": [
{
"Account": {
"AccountNumber": "90c68cb4-e44d-42c7-9b03-1b3845636e60",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"AccountHolderName": "User1,Test",
"AccountBalance": "0",
"Overdraft": "0",
"AvailableBalance": "0",
"Type": "",
"Currency": "bct",
"CurrencyType": "",
"Timestamp": 0,
"WalletAddress": "mfeyrbigCqw6NDzZXATkyic5Jd8ZUieTuA",
"AccountHolderID": ""
},
"AccountMeta": {
"bvnk_account_name": "calypso calypso",
"bvnk_private_resource": "yes",
"namespace": "user_8604125138082100"
}
},
{
"Account": {
"AccountNumber": "165482e1-0acd-4b3c-b737-3c3b67203128",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"AccountHolderName": "User1,Test",
"AccountBalance": "0",
"Overdraft": "0",
"AvailableBalance": "0",
"Type": "",
"Currency": "bct",
"CurrencyType": "",
"Timestamp": 0,
"WalletAddress": "moa42qAWq6B5zM7mChuaCqTGX6s9jSesm4",
"AccountHolderID": ""
},
"AccountMeta": {
"bvnk_account_name": "east athena",
"bvnk_private_resource": "yes",
"namespace": "user_8604125138082100"
}
}
]
}

Error response:

{
"error": "Could not retrieve account listing"
}

Funding Wallets

Accounts can be funded using a ‘Faucet’. One can be found here. Simply add the WalletAddress to the field provided and complete the reCAPTCHA process.

Example of a Faucet

Note: this process can take anywhere from 10 minutes to a few hours depending on the network.

Balances can be checked by repeating the above step.

Credit Transfer

Enter: transactions. Funds can be sent to accounts existing on BVNK or even to external wallets using the same call. When more currencies are supported, automatic exchange will take place between BVNK accounts. This will allow a user to send any amount from one cryptocurrency account to any other cryptocurrency account within BVNK.

POST https://demo.bvnk.co/transaction/credit

Note: cryptocurrency can be sent to external wallets by specifying the RecipientDetails as the wallet address.

curl -X POST \
https://demo.bvnk.co/transaction/credit \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'postman-token: f7befd14-cd7b-52be-b7f4-f500fde4c55e' \
-H 'x-auth-token: 870b08c5-b45b-4e7b-95ac-779cad191939' \
-F SenderDetails=e0e712e4-b5e2-4b03-a401-1c828e0f2726@ \
-F RecipientDetails=9bd356cd-1c54-498d-b6b5-26a8d0a17940@ \
-F Amount=20 \
-F Lat=11.0 \
-F Lon=12.0 \
-F 'Desc=Test desc'

Successful response:

{
"response": "490923"
}

Error response:

{
"error": "Insufficient funds available"
}

Transaction List

Finally, we can check the transactions made on an account. This call retrieves a given number of transactions on an account.

GET https://demo.bvnk.co/transaction/list/{perPage}/{pageNum}

Note: the account number is determined through an additional header X-Auth-AccountNumber . It also needs to be the account of the logged in user.

curl -X GET \
https://demo.bvnk.co/transaction/list/10/0 \
-H 'cache-control: no-cache' \
-H 'postman-token: e179488a-ef39-4c04-724d-55697acb79f7' \
-H 'x-auth-accountnumber: e0e712e4-b5e2-4b03-a401-1c828e0f2726' \
-H 'x-auth-token: 6c2eb753-0ae3-4176-9d3d-d8f723671e78'

Successful response:

{
"response": [
{
"ID": 490925,
"PainType": 1002,
"Sender": {
"AccountNumber": "e0e712e4-b5e2-4b03-a401-1c828e0f2726",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"Name": "bvnk,Alice"
},
"Receiver": {
"AccountNumber": "0",
"BankNumber": "0",
"Name": ""
},
"Amount": "-8",
"Fee": "0.0007999999797903001",
"Geo": [
10,
10
],
"Desc": "????",
"Status": "approved",
"Timestamp": 1505652044
},
{
"ID": 490924,
"PainType": 1000,
"Sender": {
"AccountNumber": "0",
"BankNumber": "0",
"Name": ""
},
"Receiver": {
"AccountNumber": "e0e712e4-b5e2-4b03-a401-1c828e0f2726",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"Name": "bvnk,Alice"
},
"Amount": "120",
"Fee": "0.012000000104308128",
"Geo": [
10,
10
],
"Desc": "",
"Status": "approved",
"Timestamp": 1505651801
},
{
"ID": 490923,
"PainType": 1,
"Sender": {
"AccountNumber": "e0e712e4-b5e2-4b03-a401-1c828e0f2726",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"Name": "bvnk,Alice"
},
"Receiver": {
"AccountNumber": "9bd356cd-1c54-498d-b6b5-26a8d0a17940",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"Name": "bvnk,Alice"
},
"Amount": "-20",
"Fee": "0.0020000000949949026",
"Geo": [
11,
12
],
"Desc": "Test desc",
"Status": "approved",
"Timestamp": 1505650285
},
{
"ID": 490922,
"PainType": 1000,
"Sender": {
"AccountNumber": "0",
"BankNumber": "0",
"Name": ""
},
"Receiver": {
"AccountNumber": "e0e712e4-b5e2-4b03-a401-1c828e0f2726",
"BankNumber": "a0299975-b8e2-4358-8f1a-911ee12dbaac",
"Name": "bvnk,Alice"
},
"Amount": "120",
"Fee": "0.012000000104308128",
"Geo": [
10,
10
],
"Desc": "????",
"Status": "approved",
"Timestamp": 1505650282
}
]
}

Error response:

{
"error": "Cannot retrieve more than 100 results per request"
}

Conclusion

There is a host of other functionality available in our API documentation and this article serves as a good start for developers not familiar with BVNK. Testing on our demo instance is open, but in order to utilise real Bitcoin, a developer should get in touch with us to be issued keys. For larger, more specialised or custom implementations, please don’t hesitate to reach out to our business development team here.

If this article was helpful, please give us ‘claps’ or share it. It helps us help more people.


Have a suggestion to make BVNK easier?

To share feedback, make comments or suggestions, or say hi, please email usor join our community on Telegram. Alternatively follow us on Twitter or Facebook.


Simple Modern Finance

BVNK is a turnkey enabling technology for the purchase, storage and general utility of cryptocurrencies for businesses and individuals.

Our mission is to provide progressive financial services to anyone and enable anyone to do the same.

Find out more here, download our white paper here, or to get in touch to request access to our beta application.

Like what you read? Give BVNK a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.