## **Integrate Cardano**

**Introduction**

Here we show you how to integrate Cardano into existing websites and services.

**Integration Components**

[Overview](https://developers.cardano.org/docs/get-started/cardano-node/cardano-components) of the different Cardano components.

[cardano-node](https://github.com/IntersectMBO/cardano-node) is the top level for the node and aggregates the other components from other packages: consensus, ledger and networking, with configuration, CLI, logging and monitoring.

[cardano-wallet](https://github.com/cardano-foundation/cardano-wallet) helps you manage ada. You can use it to send and receive payments on the Cardano blockchain via a http and cli interface.

[cardano-db-sync](https://github.com/IntersectMBO/cardano-db-sync) follows the Cardano chain and takes information from the chain and an internally maintained copy of ledger state. Data is then extracted from the chain and inserted into a PostgreSQL database.

[cardano-graphql](https://github.com/cardano-foundation/cardano-graphql) a cross-platform, typed, and queryable API for Cardano.

[cardano-rosetta](https://github.com/cardano-foundation/cardano-rosetta) a multi-platform implementation of Rosetta for Cardano, targeting the version defined in the OpenApi schema.

[cardano-addresses](https://github.com/IntersectMBO/cardano-addresses) provides mnemonic (backup phrase) creation, and conversion of a mnemonic to seed for wallet restoration, and address derivation functionalities.

**Tutorials**

[Explore Cardano wallets](https://developers.cardano.org/docs/integrate-cardano/creating-wallet-faucet) - learn how to create a Cardano wallet, receive test ada and create basic transactions.

[Multi-witness transactions](https://developers.cardano.org/docs/integrate-cardano/multi-witness-transactions-cli) - learn how to create transactions with multiple inputs and one output.

[Listening for ada payments using cardano-cli ](https://developers.cardano.org/docs/integrate-cardano/listening-for-payments-cli)- how to listen to a specific address using cardano-cli.

[Listening for ada payments using cardano-wallet](https://developers.cardano.org/docs/integrate-cardano/listening-for-payments-wallet) - how to listen to a specific address using cardano-wallet.

[Testnet Faucet](https://developers.cardano.org/docs/integrate-cardano/testnet-faucet) - a service that provides test ada (tAda) to users of the Cardano testnets.

[Sample queries](https://iohk.zendesk.com/hc/en-us/articles/4402395914009-Sample-cardano-rosetta-queries) for cardano-rosetta.

[Sample queries](https://iohk.zendesk.com/hc/en-us/articles/900000906566-Sample-cardano-graphql-queries) for cardano-graphql.

**Exchange Integration**

[Exchange integration overview](https://iohk.zendesk.com/hc/en-us/articles/900000911923-Exchange-integration-overview)

[Exchange integration guidelines](https://iohk.zendesk.com/hc/en-us/articles/900000919406-Exchange-integration-guidelines)


Integrate Cardano

Exploring Cardano wallets

## **Multi-witness transactions**

**Overview**

**note**

This guide assumes that you have completed the Exploring Cardano Wallets guide. You will need one UTxO sitting at each of the wallets (payment1.addr and payment2.addr) to complete this guide.

This guide also assumes that you have cardano-node running in the background and connected to a testnet network.

**Recap**

Let's recap what we did so far. Our goal in the previous guide was to draw 1000 tADA from the Testnet Faucet and send 250 tAda from payment1 to payment2.

Make sure we are in the correct folder.

`$ pwd
$HOME/cardano`

**Query UTxO**

We drew 1000 tAda from the Testnet Faucet into our payment1 wallet.

`$ cardano-cli query utxo \
--testnet-magic 1097911063 \
--address $(cat keys/payment1.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
264c0aa805652e3607c5ea2b1e8a9f3bf9c3bc8d4d938e1a9035f352083ba703     0        1000000000 lovelace`

We currently have 749.825831 tAda in our payment1 wallet and 250 tAda in our payment2 wallet.

Let's see how we can spend it all at once!

**Calculate fees**

We used protocol-parameters to draft our transaction and calculated the expected fee.
`$ cardano-cli query protocol-parameters \
--testnet-magic 1097911063 \
--out-file protocol.json`

`$ cardano-cli conway transaction build-raw \
--tx-in 264c0aa805652e3607c5ea2b1e8a9f3bf9c3bc8d4d938e1a9035f352083ba703#0 \
--tx-out $(cat keys/payment2.addr)+0 \
--tx-out $(cat keys/payment1.addr)+0 \
--fee 0 \
--out-file tx.draft`

`$ cardano-cli conway transaction calculate-min-fee \
--tx-body-file tx.draft \
--tx-in-count 1 \
--tx-out-count 2 \
--witness-count 1 \
--testnet-magic 1097911063 \
--protocol-params-file protocol.json
174169 Lovelace`

We currently have 749.825831 tAda in our payment1 wallet and 250 tAda in our payment2 wallet.

Let's see how we can spend it all at once!

**Build Tx**

From the expected fee of 174169 Lovelace, we were able to calculate the outputs and build our transaction.

`cardano-cli conway transaction build-raw \
--tx-in 264c0aa805652e3607c5ea2b1e8a9f3bf9c3bc8d4d938e1a9035f352083ba703#0 \
--tx-out $(cat keys/payment2.addr)+250000000 \
--tx-out $(cat keys/payment1.addr)+749825831 \
--fee 174169 \
--out-file tx.draft`

We currently have 749.825831 tAda in our payment1 wallet and 250 tAda in our payment2 wallet.

Let's see how we can spend it all at once!

**Sign & Submit Tx**

We used payment1.skey to sign our transaction and submitted it to the blockchain.

`cardano-cli conway transaction sign \
--tx-body-file tx.draft \
--signing-key-file keys/payment1.skey \
--testnet-magic 1097911063 \
--out-file tx.signed

cardano-cli conway transaction submit \
--tx-file cardano/tx.signed \
--testnet-magic 1097911063
Transaction successfully submitted.`

We currently have 749.825831 tAda in our payment1 wallet and 250 tAda in our payment2 wallet.

Let's see how we can spend it all at once!

**Verify Tx**

Finally we verified the transaction by querying the payment1 and payment2 wallets.

`$ cardano-cli query utxo \
--testnet-magic 1097911063 \
--address $(cat keys/payment1.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
b73b7503576412219241731230b5b7dd3b64eed62ccfc3ce69eb86822f1db251     1        749825831 lovelace`

`$ cardano-cli query utxo \
--testnet-magic 1097911063 \
--address $(cat payment2.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
b73b7503576412219241731230b5b7dd3b64eed62ccfc3ce69eb86822f1db251     0        250000000 lovelace`

We currently have 749.825831 tAda in our payment1 wallet and 250 tAda in our payment2 wallet.

Let's see how we can spend it all at once!

Use case
There are many possible reasons why you would want to have multiple wallets sending their ada in a single transaction. One is, you own two wallets (payment1 and payment2) and you want to spend it on something that...

costs more than you have in any of your two wallets,
but both amounts combined would cover the costs.
Let's say you are at the bike store and you see a nice bike with a price tag of 1100 tAda on it. You only have 999 tAda (plus change) left.

The bike store owner - a devious blockchain enthusiast - is willing to give you a 10% discount, if you manage to pay him in a single transaction

There has to be no change, buddy! --Bike Store Owner

So we need to make sure to spend all our tAda from our two wallets in a single transaction.

**note**

He can easily verify if we spent all our money by checking if the transaction has more than one output.

There are ways to optimize the amount you spend. We will leave this for you to figure out yourself.

**Technical Flow**

This scenario is pretty straight forward and looks like this.

![](https://developers.cardano.org/assets/images/multi-witness-transaction-8c57b0b78c7ad502d62713d0bd22a5a3.png)

As you can see in the diagram above, we will build and submit a multi-witness transaction, having two inputs and one output.

note
We can't do this with cardano-wallet, or any other wallet like Daedalus or Yoroi because we will need both signing-keys from payment1 and payment2 to sign the transaction.

Time to code
note
As mentioned above, this guide assumes you completed the Exploring Cardano Wallets guide.
We also assume you paid 174169 Lovelace in transaction fees and that your current balances are:

payment1: 749825831 Lovelace
payment2: 250000000 Lovelace
Create a store-owner wallet
If you don't already have a third wallet to use for this guide, let's create one where we can transfer all our funds to.

Make sure you are inside the keys directory like so: cd $HOME/cardano/keys

Generate a payment key-pair using cardano-cli:

cardano-cli address key-gen \
--verification-key-file $HOME/cardano/keys/store-owner.vkey \
--signing-key-file $HOME/cardano/keys/store-owner.skey

Then generate a wallet address for the testnet network:

cardano-cli address build \
--payment-verification-key-file $HOME/cardano/keys/store-owner.vkey \
--out-file $HOME/cardano/keys/store-owner.addr \
--testnet-magic 1097911063

Check your keys directory. It should look something like this:

$HOME/cardano/keys/
├── payment1.addr
├── payment1.skey
├── payment1.vkey
├── payment2.addr
├── payment2.skey
├── payment2.vkey
├── store-owner.addr
├── store-owner.skey
└── store-owner.vkey

0 directories, 9 files

Calculate the transaction fee
Lets create a directory to store our transactions for this guide and enter it:

mkdir -p $HOME/cardano/multi-witness-sample && cd $_;

We want to send all our tAda sitting at the two UTxO we verified before and send it to the store-owner.addr. That means we will have two inputs.

What about the outputs? Well, the devious store-owner wants us to spend it all, so there will be one output to the store-owner and zero outputs to us. Remember? "...no change, buddy!"

Lets build that transaction.

cardano-cli conway transaction build-raw \
--tx-in b73b7503576412219241731230b5b7dd3b64eed62ccfc3ce69eb86822f1db251#0 \
--tx-in b73b7503576412219241731230b5b7dd3b64eed62ccfc3ce69eb86822f1db251#1 \
--tx-out $(cat ../keys/store-owner.addr)+0 \
--fee 0 \
--out-file tx2.draft

The last thing we need to do is to calculate the fees for tx2.draft. Notice the --tx-in-count and --witness-count.

cardano-cli conway transaction calculate-min-fee \
--tx-body-file tx2.draft \
--tx-in-count 2 \
--tx-out-count 1 \
--witness-count 2 \
--testnet-magic 1097911063 \
--protocol-params-file ../protocol.json 
179581 Lovelace

We can calculate the amount the store-owner will receive, if both UTxO are spent during the transaction:

  749825831 (payment1)
+ 250000000 (payment2)
  ---------
  999825831
-    179581 (fee)
  ---------
  999646250 (store-owner)
  =========

Build, sign and submit transaction
We know the output amount as well as the fee. We can finally build, sign and submit our tx2.draft transaction.

We have to use payment1.skey and payment2.skey to sign our transaction.

cardano-cli conway transaction build-raw \
--tx-in b73b7503576412219241731230b5b7dd3b64eed62ccfc3ce69eb86822f1db251#0 \
--tx-in b73b7503576412219241731230b5b7dd3b64eed62ccfc3ce69eb86822f1db251#1 \
--tx-out $(cat ../keys/store-owner.addr)+999646250 \
--fee 179581 \
--out-file tx2.draft 

cardano-cli conway transaction sign \
--tx-body-file tx2.draft \
--signing-key-file ../keys/payment1.skey \
--signing-key-file ../keys/payment2.skey \
--testnet-magic 1097911063 \
--out-file tx2.signed

cardano-cli conway transaction submit \
--tx-file tx2.signed \
--testnet-magic 1097911063
Transaction successfully submitted

Verify multi-witness transactions
The devious store-owner will now verify that everything went according to his plan.

cardano-cli query utxo \
--testnet-magic 1097911063 \
--address $(cat $HOME/cardano/keys/store-owner.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
258abd628eef7d6ff0f7b4e6866b4f7c21065f4d6b5e49b51e2ac4ff035ad06f     0        999646250 lovelace

Success!
He can see that the transaction has one output to his wallet. No other outputs, hence you must have spent all of your tAda.

Congratulations, you are now able to submit multi-witness transactions on Cardano. This should help you bring integrations to your existing or new upcoming applications. 🎉🎉🎉


Multi-witness transactions

Listening for ada payments using cardano-cli

## **Listening for ada payments using cardano-wallet**

**Overview**

note

This guide assumes that you have basic understanding of cardano-wallet, how to use it and that you have installed it into your system. Otherwise we recommend reading Installing cardano-node, Running cardano-node and Exploring Cardano Wallets guides first.

This guide also assumes that you have cardano-node and cardano-wallet running in the background and connected to a testnet network.

**Use case**

There are many possible reasons why you would want to have the functionality of listening for ada payments, but a very obvious use case would be for something like an online shop or a payment gateway that uses ada tokens as the currency.

![](https://developers.cardano.org/assets/images/ada-online-shop-0dee5526d39fa5fc40c8e722f1fd0f6b.png)

**Technical flow**

To understand how something like this could work in a technical point of view, let's take a look at the following diagram:

![](https://developers.cardano.org/assets/images/ada-payment-flow-wallet-ca3d46bbad3e6722fabf41a8201b6bc1.png)

So let's imagine a very basic scenario where a customer is browsing an online shop. Once the user has chosen and added all the items into the shopping cart. The next step would then be to checkout and pay for the items, Of course we will be using Cardano for that!

The front-end application would then request for a wallet address from the backend service and render a QR code to the customer to be scanned via a Cardano wallet. The backend service would then know that it has to query the cardano-wallet with a certain time interval to confirm and alert the front-end application that the payment has completed successfully.

In the meantime the transaction is then being processed and settled within the Cardano network. We can see in the diagram above that both parties are ultimately connected to the network via the cardano-node software component.

**Time to code**

Now let's get our hands dirty and see how we can implement something like this in actual code.

**Generate wallet and request tAda**

First, we create our new wallet via cardano-wallet REST API:

**Generate seed**

**JavaScript**

`// Please add this dependency using npm install node-cmd
import cmd from 'node-cmd';
const mnemonic = cmd.runSync(["cardano-wallet","recovery-phrase", "generate"].join(" ")).data;
`

**Typescript**

`// Please add this dependency using npm install node-cmd but there is no @type definition for it
const cmd: any = require('node-cmd');

const mnemonic: string = cmd.runSync(["cardano-wallet", "recovery-phrase", "generate"].join(" ")).data;`

**Python**

`import subprocess

mnemonic = subprocess.check_output([
    'cardano-wallet', 'recovery-phrase', 'generate'
])`

**C#**

`using System;
using SimpleExec; // dotnet add package SimpleExec --version 7.0.0

var mnemonic = await Command.ReadAsync("cardano-wallet", "recovery-phrase generate", noEcho: true);`

**Restore wallet from seed**

We will then pass the generated seed to the wallet create / restore endpoint of cardano-wallet.

**JavaScript**

`// Please add this dependency using npm install node-fetch
import fetch from 'node-fetch';

const resp = await fetch("http://localhost:9998/v2/wallets", {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: "test_cf_1",
        mnemonic_sentence: ["expose", "biology", "will", "pause", "taxi", "behave", "inquiry", "lock", "matter", "pride", "divorce", "model", "little", "easily", "solid", "need", "dose", "sadness", "kitchen", "pyramid", "erosion", "shoulder", "double", "fragile"],
        passphrase: "test123456"
    })
});`

**Typescript**

`// Please add this dependency using npm install node-fetch and npm install @types/node-fetch
import fetch from 'node-fetch';
import { Response } from 'node-fetch';

const resp: Response = await fetch("http://localhost:9998/v2/wallets", {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: "test_cf_1",
        mnemonic_sentence: ["expose", "biology", "will", "pause", "taxi", "behave", "inquiry", "lock", "matter", "pride", "divorce", "model", "little", "easily", "solid", "need", "dose", "sadness", "kitchen", "pyramid", "erosion", "shoulder", "double", "fragile"],
        passphrase: "test123456"
    })
});`

**Python**

`# pip install requests
import requests

data = {
    'name'                  :   'test_cf_1',
    'mnemonic_sentence'     :  ["expose", "biology", "will", "pause", "taxi", "behave", "inquiry", "lock", "matter", "pride", "divorce", "model", "little", "easily", "solid", "need", "dose", "sadness", "kitchen", "pyramid", "erosion", "shoulder", "double", "fragile"],
    'passphrase'            :   'test123456'
}

r = requests.post("http://localhost:9998/v2/wallets", json=data)`

**C#**

`using System;
using System.Net.Http;
using System.Net.Http.Json;

// Restore the wallet using the previously generated seed. Assuming cardano-wallet is listening on port 9998
using var http = new HttpClient() { BaseAddress = new Uri("http://localhost:9998/v2/") };

var resp = await http.PostAsJsonAsync("wallets", new {
    name = "test_cf_1",    
    mnemonic_sentence = new[] { "expose", "biology", "will", "pause", "taxi", "behave", "inquiry", "lock", "matter", "pride", "divorce", "model", "little", "easily", "solid", "need", "dose", "sadness", "kitchen", "pyramid", "erosion", "shoulder", "double", "fragile" },    
    passphrase = "test123456"
});`

**Get unused wallet address to receive some payments**

We will get a wallet address to show to the customers and for them to send payments to the wallet. In this case we can use the address to request some tAda from the Cardano Testnet Faucet and simulate a payment:

**Retrieve wallet balance**

We will then retrieve the wallet details to get stuff like its sync status, native assets and balance (lovelace). We can then use the balance to check if we have received a some payment.

**JavaScript**

`// Please add this dependency using npm install node-fetch
import fetch from 'node-fetch';
const walletId = "101b3814d6977de4b58c9dedc67b87c63a4f36dd";
// The total payment we expect in lovelace unit
const totalExpectedLovelace = 1000000;
const resp = await fetch(`http://localhost:9998/v2/wallets/${walletId}`);
const wallet = await resp.json();
const balance = wallet.balance.total.quantity;`

**Typescript**

`// Please add this dependency using npm install node-fetch and npm install @types/node-fetch
import fetch from 'node-fetch';
import { Response } from 'node-fetch';
const walletId: string = "101b3814d6977de4b58c9dedc67b87c63a4f36dd";
// The total payment we expect in lovelace unit
const totalExpectedLovelace = 1000000;
const resp: Response = await fetch(`http://localhost:9998/v2/wallets/${walletId}`);
const wallet: any = await resp.json();
const balance: number = wallet.balance.total.quantity;`

**Python**

`# pip install requests
import requests
walletId = '101b3814d6977de4b58c9dedc67b87c63a4f36dd'
# The total payment we expect in lovelace unit
totalExpectedLovelace = 1000000;
r = requests.get('http://localhost:9998/v2/wallets/%s' % walletId)
wallet = r.json()
balance = wallet['balance']['total']['quantity']`

**C#**

`using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient() { BaseAddress = new Uri("http://localhost:9998/v2/") };
// Get Wallet Details / Balance
// Replace with your wallet Id
var walletId = "101b3814d6977de4b58c9dedc67b87c63a4f36dd";
// The total payment we expect in lovelace unit
var totalExpectedLovelace = 1000000;

var wallet = await http.GetFromJsonAsync<JsonElement>($"wallets/{walletId}");
var balance = wallet.GetProperty("balance").GetProperty("total").GetProperty("quantity").GetInt32();`

**Determine if payment is successful**

Once we have the total lovelace amount, we will then determine using our code if a specific payment is a success, ultimately sending or shipping the item if it is indeed successful. In our example, we expect that the payment is equal to 1,000,000 lovelace that we defined in our totalExpectedLovelace constant.

**JavaScript**

`// Check if payment is complete
const isPaymentComplete = balance >= totalExpectedLovelace;

console.log(`Total Received: ${balance} LOVELACE`);
console.log(`Expected Payment: ${totalExpectedLovelace} LOVELACE`);
console.log(`Payment Complete: ${(isPaymentComplete ? "✅":"❌")}`);`

**Typescript**

`// Check if payment is complete
const isPaymentComplete: boolean = balance >= totalExpectedLovelace;

console.log(`Total Received: ${balance} LOVELACE`);
console.log(`Expected Payment: ${totalExpectedLovelace} LOVELACE`);
console.log(`Payment Complete: ${(isPaymentComplete ? "✅":"❌")}`);`

**Python**

`# Check if payment is complete
isPaymentComplete = balance >= totalExpectedLovelace

print("Total Received: %s LOVELACE" % balance)
print("Expected Payment: %s LOVELACE" % totalExpectedLovelace)
print("Payment Complete: %s" % {True: "✅", False: "❌"} [isPaymentComplete])`

**C#**

`// Check if payment is complete
var isPaymentComplete = balance >= totalExpectedLovelace;

Console.WriteLine($"Total Received: {balance} LOVELACE");
Console.WriteLine($"Expected Payment: {totalExpectedLovelace} LOVELACE");
Console.WriteLine($"Payment Complete: {(isPaymentComplete ? "✅":"❌")}");`

**Running and testing**

Our final code should look something like this:

**JavaScript**

`// Please add this dependency using npm install node-fetch
import fetch from 'node-fetch';
const walletId = "101b3814d6977de4b58c9dedc67b87c63a4f36dd";
// The total payment we expect in lovelace unit
const totalExpectedLovelace = 1000000;
const resp = await fetch(`http://localhost:9998/v2/wallets/${walletId}`);
const wallet = await resp.json();
const balance = wallet.balance.total.quantity;

// Check if payment is complete
const isPaymentComplete = balance >= totalExpectedLovelace;

console.log(`Total Received: ${balance} LOVELACE`);
console.log(`Expected Payment: ${totalExpectedLovelace} LOVELACE`);
console.log(`Payment Complete: ${(isPaymentComplete ? "✅":"❌")}`);`

Now we are ready to test 🚀, running the code should give us the following result:

**JavaScript**

`❯ node checkPayment.js
Total Received: 0 LOVELACE
Expected Payment: 1000000 LOVELACE
Payment Complete: ❌`

The code is telling us that our current wallet has received a total of 0 lovelace and it expected 1,000,000 lovelace, therefore it concluded that the payment is not complete.

Complete the payment
What we can do to simulate a successful payment is to send at least 1,000,000 lovelace into the wallet address that we have just generated for this project. We show how you can get the wallet address via code in the examples above.

Now simply send at least 1,000,000 lovelace to this wallet address or request some test ada funds from the Cardano Testnet Faucet. Once complete, we can now run the code again and we should see a successful result this time.

**JavaScript**

`❯ node checkPayment.js
Total Received: 1000000000 LOVELACE
Expected Payment: 1000000 LOVELACE
Payment Complete: ✅`

**Typescript**

`❯ ts-node checkPayment.ts
Total Received: 1000000000 LOVELACE
Expected Payment: 1000000 LOVELACE
Payment Complete: ✅`

**Python**

`❯ python checkPayment.py 
Total Received: 1000000000 LOVELACE
Expected Payment: 1000000 LOVELACE
Payment Complete: ✅`

**C#**

`❯ dotnet run
Total Received: 1000000000 LOVELACE
Expected Payment: 1000000 LOVELACE
Payment Complete: ✅`

It might take 20 seconds or more for the transaction to propagate within the network depending on the network health, so you will have to be patient.

Congratulations, you are now able to detect successful Cardano payments programmatically. This should help you bring integrations to your existing or new upcoming applications. 🎉🎉🎉



Listening for ada payments using cardano-wallet

## **Receiving payments (Blockfrost API)**

Welcome to the documentation of a Point of Sale (POS) application built using Cardano APIs. This guide will walk you through the key features and functionalities of the application.

![](https://developers.cardano.org/assets/images/point-of-sale-example-2b087d0aa12883f1814ca754d6dde59b.png)

**Getting Started**

In this tutorial, we will guide you through the process of building a fully functional Point of Sale application on top of the Cardano blockchain. To get started, you will need to fork the starting point repository, which contains all the necessary files and configurations to begin building your own Point of Sale application.

The starting point repository already provides simple CSS and logic behind inputs, props passing and other things, so in this guide, we will mostly focus on connecting APIs and retrieving data from them to create a fully functional Point of Sale application using Cardano.

**note**

Make sure to run the command npm install in your terminal to install all the necessary dependencies.

Use the command npm run dev and your project will be up and running.

**Structure of the project**

`src
├── constants
├── components
├── pages
│   ├── api
|   └── index.js
├── styles
│   ├── pos.modules.css
├── .env.local
├── .env.example
├── README.md`

**Project structure rundown**

/constants/ - Contains various constant links and values that are used throughout application.

/components/ - Contains various reusable components that can be used throughout application.

/pages/ - Contains pages and APIs.

/styles/ - Contains all of the styling files.

.env.local - Contains API keys.
.env.example - Contains example of how your API keys should be stored.

**Requirements**

We'll need to obtain API keys for both services. These API keys will allow us to access the data and functionality we need to build and test our application.

note
Please refer to .env.example in the repo and create .env.local file. Your keys should be stored there.

**Get Blockfrost Key**

Please follow Get Started with Blockfrost to obtain Blockfrost 

**API key**

In the code, go to environment file .env.local and put the key into BLOCKFROST_API_KEY.
Get CoinMarketCap Key
Go to CoinMarketCap and sign in to your account.
Once you're signed in, navigate to your dashboard.
Copy API Key.
In the code, go to environment file .env.local and put the key into COINMARKETCAP_API_KEY.

**Adding Constants**

Before creating any API requests, it is important to add constants such as base URLs and endpoints. These constants will be used throughout the project and will make it easier to make changes or updates in the future.

Navigate to constants folder, create links.js file and insert the following based on network you will be using:

**Preview**

`export const LINKS = {
  CARDANO_SCAN: "https://preview.cardanoscan.io/address/",
  BLOCKFROST_ADDRESS: "https://cardano-preview.blockfrost.io/api/v0/addresses/",
  COINMARKETCAP_ADA_USD_PAIR:
    "https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=ADA&convert=USD",
};`

**Pre-Production**

`export const LINKS = {
  CARDANO_SCAN: "https://preprod.cardanoscan.io/address/",
  BLOCKFROST_ADDRESS: "https://cardano-preprod.blockfrost.io/api/v0/addresses/",
  COINMARKETCAP_ADA_USD_PAIR:
    "https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=ADA&convert=USD",
};`

**Mainnet**

`export const LINKS = {
  CARDANO_SCAN: "https://cardanoscan.io/address/",
  BLOCKFROST_ADDRESS: "https://cardano-mainnet.blockfrost.io/api/v0/addresses/",
  COINMARKETCAP_ADA_USD_PAIR:
    "https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=ADA&convert=USD",
};`

**Creating API files**

In api folder create blockfrost.js file and insert the following code:

`import { LINKS } from "../../constants/links";

export default async function handler(req, res) {
  const { address } = req.query;
  const projectId = process.env.BLOCKFROST_API_KEY;
  const url = LINKS.BLOCKFROST_ADDRESS + address + "/total";

  const response = await fetch(url, {
    headers: {
      "Content-Type": "application/json",
      project_id: projectId,
    },
  });

  const data = await response.json();

  res.status(200).json({ value: data });
}`

In this file, we are creating an API request to Blockfrost using personal key. We use constant link address and submit projectId to get a data response.

Now let’s do the same with CoinMarketCap. Add coinmarketcap.js file into api folder to receive pair data:

`import { LINKS } from "../../constants/links";

export default async function handler(req, res) {
  const url = LINKS.COINMARKETCAP_ADA_USD_PAIR;

  const response = await fetch(url, {
    headers: {
      "X-CMC_PRO_API_KEY": process.env.COINMARKETCAP_API_KEY,
    },
  });

  const data = await response.json();
  const adaPrice = data.data.ADA.quote.USD.price;

  res.status(200).json({ value: adaPrice });
}`

In this file, we are creating another API request to CoinMarketCap to receive price of 1 ada in USD.

**Connecting APIs**

Now that all of the APIs are set up and ready to be used, it's time to move onto the index.js file and start adding the necessary functionalities and API requests.

To fetch the ada-usd price upon loading the page, we need to add the fetchAdaPrice and useEffect functions to the index.js file:

`  // Fetch ada price from CoinMarketCap
  const fetchAdaPrice = async () => {
    fetch("/api/coinmarketcap")
      .then((response) => {
        if (!response.ok) {
          throw new Error("Network response was not ok");
        }
        return response.json();
      })
      .then((data) => setAdaValue(data.value))
      .catch((error) => console.error("Error:", error));
  };

  useEffect(() => {
    const fetchPrice = async () => {
      await fetchAdaPrice();
    };
    fetchPrice();
  }, []);`

This code will make an API request to retrieve the current price and display it on the page for the user to see. The fetchAdaPrice function will perform an API request to CoinMarketCap and set the adaValue state with the current value. Later on, in the return statement, the calculated value based on the input amount will be displayed as:

{amount} $ = {(amount / adaValue).toFixed(2)} ₳ 

**Connecting Blockfrost API to Popup**

Next, we will add some Blockfrost API requests to the popup to compare the inserted address balance and see if the transaction went through successfully.

Navigate to components folder into popup.js. The current popup generates a QR code for users to scan, which redirects with a CIP-13 URI guidelines and automatically fills in the details for the transaction, such as the address and the amount to be sent. For now, the application does not connect to the API, so we need to add a few functions to ensure application able to retrieve the necessary data from the API.

First, lets add fetchAddressQuantityOnOpen function to fetch balance of the address:

`  // Fetch balance of ada in the address when opening popup
  const fetchAddressQuantityOnOpen = async () => {
    address.length &&
      fetch(`/api/blockfrost?address=${address}`)
        .then((response) => {
          if (!response.ok) {
            throw new Error("Network response was not ok");
          }
          return response.json();
        })
        .then((data) => {
          if (data.value.received_sum) {
            setBalance(data.value.received_sum[0].quantity / 1000000);
          }
        })
        .catch((error) => console.error("Error:", error));
  };`

This function will store current balance in the store called balance.

Now let’s create another function called CompareQuantity that fetches address balance but checks it every few seconds:

`  // Fetch balance of ada in the address every few seconds to compare it with the initial balance from fetchAddressQuantityOnOpen()
  const CompareQuantity = async () => {
    fetch(`/api/blockfrost?address=${address}`)
      .then((response) => {
        if (!response.ok) {
          throw new Error("Network response was not ok");
        }
        return response.json();
      })
      .then((data) => {
        if (data.value.received_sum) {
          setNewBalance(data.value.received_sum[0].quantity / 1000000);
        }
      })
      .catch((error) => console.error("Error:", error));
  };

  // Fetch ada balance every 3 seconds
  useEffect(() => {
    address && fetchAddressQuantityOnOpen(address);
    const interval =
      address &&
      setInterval(() => {
        const result = CompareQuantity(address);
        return result;
      }, 3000);
    return () => clearInterval(interval);
  }, [address]);`

This function will store new balance in the store called newBalance state and using useEffect will continue fetching data every few seconds.

Later on in the code, we compare balance and newBalance states. If newBalance is greater or equal by the amount requested, the Waiting for payment… will be changed to Payment received successfully

Here it how it looks:

`  {newBalance - balance >= amount ? (
    <DialogContentText className={styles.approvedConfirmation}>
      Payment received successfully
    </DialogContentText>
  ) : (
    <DialogContentText className={styles.waitingConfirmation}>
      Waiting for payment...
    </DialogContentText>
  )}`

Adding CardanoScan Redirect
To add a redirect to CardanoScan in the href attribute of our popup component, we need to add the following code into our application.

import { LINKS } from "../constants/links";

Locate into return section and uncomment the following section:

`    <a
      className={styles.href}
      // href={LINKS.CARDANO_SCAN + address}
      target="_blank"
    >
      {address.substring(0, 30) + "..."}
    </a>`

Congratulations! Your Point of Sale application using Cardano is now fully functional and ready to use. You can test it by entering an amount and address into the inputs, scanning the generated QR code, performing a transaction and waiting for confirmation on the popup screen.


Receiving payments (Blockfrost API)

## **Testnet Faucet**

The Testnet Faucet is a service that provides test ada (tAda) to users of the Cardano testnets. These tokens have no value, but they enable users to experiment with Cardano testnet features without spending real ada on the Mainnet. You can use test ada to mint native tokens, to play around with Cardano wallets or to learn how to operate a stake pool.

**Testnets faucet**

This portal allows you to send test ada to your wallet. You can access it here.

**Return the test ada**

Send your test tokens to this address: addr_test1qqr585tvlc7ylnqvz8pyqwauzrdu0mxag3m7q56grgmgu7sxu2hyfhlkwuxupa9d5085eunq2qywy7hvmvej456flknswgndm3

**How to get test ada**

Define your environment. You can get tada for either the preview or preprod testnets.
Define your action. Select Receive test ADA in this case. You can also ask for pool delegation if you are managing a pool (learn more).

Enter the address of the account where you want to top up funds.

If you have been issued with an API key, please enter this to access any additional funds you may have been allocated.
Confirm the I'm not a robot box and solve the captcha if needed.

Click on Request and the funds will be in the testnet account you specified within a few minutes. Use the Cardano PreProd Testnet Explorer and Cardano PreView Testnet Explorer provided by Cardanoscan.io in case you want to check any transactions on a Cardano testnet.

Testnet Faucet

## **Authenticating users with their Cardano wallet**

**Overview**

This guide is a walkthrough on how to implement the message signing described in CIP-08 in order to authenticate users on the web with just their CIP-30-compatible wallet app.

note

There are 2 components used in this guide — the front-end and the back-end. In order to implement this example, a nodejs server is needed to run the back-end component that will receive and process the signed message submitted by the user.

**Use cases**

The following are a just some examples of where this implementation can be used:

Authenticating holders of a specific native token in order to grant access to exclusive content or service

Authenticating wallet or stake address owners for registration to some whitelist

Authenticating wallet or stake address owners when claiming native token rewards

**Time to code**

As mentioned above, there are 2 components in this example - the front-end and the back-end. Our front-end code will handle our interaction with the user, to prompt them to sign some message with their wallet. The signed message will then be submitted to our back-end component which will parse the message and verify the user's signature.

In this example, we will be asking the user to sign a simple text message containing the string account: , followed by their wallet's bech32 stake address. For example:

**account:** stake1uynpv0vlulhufm8txwry0da9qq6tn9wn42mxltq65pw403qvdcveh

Our purpose in this case is for the user to prove their ownership of the given stake address.

Also for simplicity, we will be interacting with Typhon Wallet only, in this example. But the concepts shown here should work with any other CIP-30-compliant wallet app.

**Front-end**

For brevity, our front-end component will just be an HTML page containing a single button which will start the process, when clicked by the user.

`<html>
    <head>
        <title>Authenticating users with their Cardano wallet</title>
        <script src="userWalletAuth.js"></script>
    </head>
    <body>
        <button id="login-btn">Login</button>        
    </body>
</html>`

The logic to handle the click event on the above button will be in a separate Javascript file. This is what we will really be working on for the front-end component. Let's start with the following:

`window.addEventListener("load", () => {
    const loginBtn = document.querySelector("#login-btn");
    loginBtn.addEventListener("click", authenticate);
})

async function authenticate(){
    //
}`

For now, we just attached an event listener to our button, which will call the function authenticate when clicked.

Before we go on to add functionality to authenticate and anything else, we have to first import a couple of dependencies. Let's add the following to the top of userWalletAuth.js:

`import { Buffer } from "buffer";
let csl, wallet;

async function loadCsl(){
    csl = await import("@emurgo/cardano-serialization-lib-browser/cardano_serialization_lib");
};
loadCsl();

...`

With the above lines, we just made available to the rest of our script, the Buffer package and the Cardano Serialization Library. Also, we just declared the top-level variable wallet there for convenience later. We will set its value in the following steps.

Now, let's make the authenticate function actually do some things:

`...

async function authenticate(){
    if (!csl) await loadCsl(); // make sure CSL is loaded before doing anything else.

    wallet = await window.cardano.typhoncip30.enable();

    const [stakeAddrHex, stakeAddrBech32] = await getStakeAddress();
    const messageUtf = `account: ${stakeAddrBech32}`;
    const messageHex = Buffer.from(messageUtf).toString("hex");    
    const sigData = await wallet.signData(stakeAddrHex, messageHex);
    const result = await submitToBackend(sigData);
    alert(result.message);
}`

Our authenticate function now gets the user's stake address both in hex and bech32 format. It then puts together the message that we'll ask the user to sign. After converting the message into a hex string, we call the signData method on the user's wallet to prompt the user to sign. When we get the signed message, we send it to our backend component to be processed and verified.

You'll notice that we called two more functions from the authenticate function. We have to add them to our code also:

`...

async function getStakeAddress(){
    const networkId = await wallet.getNetworkId();
    const changeAddrHex = await wallet.getChangeAddress();
    
    // derive the stake address from the change address to be sure we are getting
    // the stake address of the currently active account.
    const changeAddress = csl.Address.from_bytes( Buffer.from(changeAddrHex, 'hex') );
    const stakeCredential = csl.BaseAddress.from_address(changeAddress).stake_cred();
    const stakeAddress = csl.RewardAddress.new(networkId, stakeCredential).to_address();

    return [stakeAddress.to_hex(), stakeAddress.to_bech32()];
}

async function submitToBackend(sigData){
    const result = await fetch(`http://localhost:8081/login`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify(sigData),
    });
    return result.json();
}`

That completes our front-end code. It can be viewed in full here.

**Back-end**

For our back-end, let's create a file named server.js and first, we will import the dependencies we need:

`const { Buffer } = require("buffer");
const { COSESign1, COSEKey, BigNum, Label, Int } = require("@emurgo/cardano-message-signing-nodejs");
const { Ed25519Signature, RewardAddress, PublicKey, Address } = require("@emurgo/cardano-serialization-lib-nodejs");
const express = require("express");
const cors = require("cors");`

Here, we will be creating just a simple Express JS server that can receive our POST request from our front-end. Along with the others, we imported a few required classes from the cardano-message-signing and cardano-serialization-lib packages.

Now let's add a sample list of "registered users" of our app, identified by their stake addresses:

`...

const registeredUsers = [
    "stake1uyzu7upg082rqajwasmwgam09fe7yj2cm3fkdfecqgptg8cwuze7s",
    "stake1u8k7mwu8gdqyvgved89996cy6g8d9vw36w7j05qy2etanxgmgl5s7",
    "stake1uynpv0vlulhufm8txwry0da9qq6tn9wn42mxltq65pw403qvdcveh",
    "stake1uxa2x4andawqtcqxw9gy4mamdx6extq5g5grqq6pf7zpxxge4aa7l",
    "stake1ux8yttnhy6qm9lkehvnmlhufnx38ef2q8vl6xyu8gyk0zwc83nvxh",
    "stake1uykkptznwz0jd3flwa442a0cdmfrpwhg8pa9ypytf4cwacqw2085c"
]`

Next, we create our express server with one endpoint to receive the request from our front-end:

...

const app = express();
app.use(express.json());
app.options("*", cors());
app.use(cors({
    origin: "*"
}));

app.post("/login", authenticate);
app.listen(8081, () =>
  console.log("Backend component listening on port 8081!"),
);


The above code adds the /login endpoint which fires up the authenticate handler function. Now let's add that function:

`...

async function authenticate(req, res) {
    const sigData = req.body;
    const decoded = COSESign1.from_bytes( Buffer.from(sigData.signature, "hex") );
    const headermap = decoded.headers().protected().deserialized_headers();
    const addressHex = Buffer.from( headermap.header( Label.new_text("address") ).to_bytes() )
        .toString("hex")
        .substring(4);
    const address = Address.from_bytes( Buffer.from(addressHex, "hex") );

    const key = COSEKey.from_bytes( Buffer.from(sigData.key, "hex") );
    const pubKeyBytes = key.header( Label.new_int( Int.new_negative(BigNum.from_str("2")) ) ).as_bytes();
    const publicKey = PublicKey.from_bytes(pubKeyBytes);

    const payload = decoded.payload();
    const signature = Ed25519Signature.from_bytes(decoded.signature());
    const receivedData = decoded.signed_data().to_bytes();

    const signerStakeAddrBech32 = RewardAddress.from_address(address).to_address().to_bech32();
    const utf8Payload = Buffer.from(payload).toString("utf8");
    const expectedPayload = `account: ${signerStakeAddrBech32}`; // reconstructed message

    // verify:
    const isVerified = publicKey.verify(receivedData, signature);
    const payloadAsExpected = utf8Payload == expectedPayload;
    const signerIsRegistered = registeredUsers.includes(signerStakeAddrBech32);

    const isAuthSuccess = isVerified && payloadAsExpected && signerIsRegistered;

    res.send({
        success: isAuthSuccess,
        message: isAuthSuccess ? "✅ Authentication success!" : "❌ Authentication failed."
    })
}`

Let's unpack what happened there.

First, we decoded the serialized signature that was submitted by the user. From the headers of this decoded data, we got the address of the signer. We later convert it back to its bech32 format to reconstruct our expected message string.

We then created a PublicKey instance of the key that came together with the signature sent by the user. We later use this to verify the submitted signature.

We also parsed the payload from the decoded signature data. After reconstructing our expected message string, we compare it with the payload we actually received.

Since we already have the signer's stake address, we also checked it against our registeredUsers list.

Lastly, we send a response back to the user with a success message if all three checks where passed and a failure message if otherwise.

That completes our backend component. The full code can be viewed here.

**Demo project repository**

For quick and convenient testing of the above code, a demo project is available here that can be cloned and quickly run.

Authenticating users with their Cardano wallet

Welcome to the Cardano Developer Portal. This content is for technical people; if you are looking for a Cardano wallet please head to the showcase section.

It is noteworthy to mention that the Developer Portal covers everything you can do today on the Cardano mainnet.

Here we show you how to integrate Cardano into existing websites and services.

Integrate Cardano

Course Details

Level

Ratings

Modules

Lessons

Holder $WORK Price

Contact Us

Documentation

Navigation