Usage

This page contains step-by-step guide to setup and using developer-controlled wallets.

⚠️

Developer controlled wallet must be integrated on the backend, and must not be on the client.

Setup

Creating A Project

Before you begin, you need to create a project. Follow these steps:

Sign Up or Log In - Log in using one of the supported authentication providers.
Create a New Project - Access the dashboard and create a new project.
Set Up Security - Navigate to Dashboard > Project Settings > Security and configure your Entity Secret.
Secure Your Private Key - Generate and securely store your Private Key.
Copy Your API Key - Retrieve your API Key from the project settings page.

Edit Your Environment Variables

Add UTXOS_PRIVATE_KEY= and UTXOS_API_KEY= to your .env file

# .env
NEXT_PUBLIC_UTXOS_PROJECT_ID=your_project_id
BLOCKFROST_API_KEY_PREPROD=your_blockfrost_api_key # https://blockfrost.io/dashboard
UTXOS_PRIVATE_KEY=your_entity_secret # https://utxos.dev/dashboard
UTXOS_API_KEY=your_api_key # https://utxos.dev/dashboard

Installing The SDK

Install the latest version of the UTXOS SDK using npm:

npm install @meshsdk/web3-sdk

Initializing The Sdk

Import Web3Sdk and initialize it with the required parameters:

import { Web3Sdk } from "@meshsdk/web3-sdk";
 
const sdk = new Web3Sdk({
  projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
  apiKey: process.env.UTXOS_API_KEY,
  privateKey: process.env.UTXOS_PRIVATE_KEY,
  network: "preprod",
});

projectId - A public identifier for your project. Retrieve it from your project settings page.
apiKey - A secret key used to authenticate requests to UTXOS. Generate an API key in the project settings.
privateKey - The Entity Secret Private Key, which encrypts your wallet’s private keys. Generate it in the project settings.

API Reference

The following methods are available for managing developer-controlled wallets.

Creating A Wallet

To create a new wallet, use the createWallet method:

const walletInfo = await sdk.wallet.createWallet();

You can also assign a tag to the wallet for easier identification:

const walletInfo = await sdk.wallet.createWallet({ tags: ["minting"] });

Note: A tag is a string identifier that can be used to categorize or track wallets.

Get All Wallets

Fetch all wallets associated with your project:

const wallets = await sdk.wallet.getWallets();

Get A Specific Wallet

Retrieve details of a specific wallet using its wallet ID and network ID:

const { info, wallet } = await sdk.wallet.getWallet("WALLET_ID", NETWORK_ID);

Wallet API

To interact with the blockchain using Wallet APIs, you need both a fetcher and a submitter. These components handle querying blockchain data and submitting transactions, respectively.

The following example demonstrates how to use BlockfrostProvider as the provider for the SDK.

First, install the necessary packages:

npm install @meshsdk/web3-sdk @meshsdk/provider

Next, import Web3Sdk and BlockfrostProvider, then initialize the SDK. While this example uses BlockfrostProvider, you can use any other supported providers.

import { Web3Sdk } from "@meshsdk/web3-sdk";
import { BlockfrostProvider } from "@meshsdk/provider";
 
const provider = new BlockfrostProvider(`/api/blockfrost/preprod/`);
 
const sdk = new Web3Sdk({
  projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
  apiKey: process.env.UTXOS_API_KEY,
  privateKey: process.env.UTXOS_PRIVATE_KEY,
  network: "preprod",
  fetcher: provider,
  submitter: provider,
});

Once the SDK is initialized, you can create or retrieve a wallet and use various wallet-related endpoints. A comprehensive list of wallet endpoints is available in the Mesh SDK documentation. Here are a few examples:

Get Change Address

Get a change address for the wallet.

const changeAddress = await wallet.getChangeAddress();

Get Wallet’s UTXO

Get all UTXOs for the wallet.

const utxos = await wallet.getUtxos();

Sign Transaction

const signedTx = await wallet.signTx(tx, partialSign?);

Sign Data

const signature = await wallet.signData(data);

Submit Transaction

const txHash = await wallet.submitTx(signedTx);

Examples

Create, Sign, and Submit a Transaction

Here is an example of how to create a transaction, sign it, and submit it to the network.

import { Web3Sdk } from "@meshsdk/web3-sdk";
import { BlockfrostProvider, MeshTxBuilder } from "@meshsdk/core";
 
const provider = new BlockfrostProvider(`/api/blockfrost/preprod/`);
 
const sdk = new Web3Sdk({
  projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
  apiKey: process.env.UTXOS_API_KEY,
  privateKey: process.env.UTXOS_PRIVATE_KEY,
  network: "preprod",
  fetcher: provider,
  submitter: provider,
});
 
const { info, wallet } = await sdk.wallet.getWallet(
  "2769cc4df6196d87f97344774e0f9db61fe54b4d0aabf26423687b89",
  0,
);
 
const tx = new MeshTxBuilder({
  fetcher: provider,
});
 
tx.txOut("addr_test1.....abc123", [{ unit: "lovelace", quantity: "1000000" }])
  .changeAddress(await wallet.getChangeAddress())
  .selectUtxosFrom(await wallet.getUtxos());
 
const unsignedTx = await tx.complete();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

How It Works Sponsorship