Skip to main content
Get started with the Bloque SDK by creating your first virtual card account. This guide will take you from installation to making your first API call.

​
What You’ll Build

In this quickstart, you’ll:
  • Install the Bloque SDK
  • Configure authentication
  • Register a new user
  • Create a virtual account
  • Issue a virtual card

​
Before You Start

You’ll need:
  • Node.js 22+ (or Bun, Deno)
  • A Bloque API key (contact Bloque to get started)
  • Your origin identifier
1

Install the SDK

Install the Bloque SDK using your preferred package manager:
npm install @bloque/sdk
2

Set up your credentials

Create a .env file in your project root with your credentials:
.env
BLOQUE_API_KEY=your_api_key_here
BLOQUE_ORIGIN=your-origin
Never commit your API key to version control. Always use environment variables for credentials.
3

Initialize the SDK

Create a new file and import the SDK:
index.ts
import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: process.env.BLOQUE_ORIGIN!,
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'sandbox', // Use 'production' when ready
});
Start with sandbox mode for testing. Switch to production when you’re ready to go live.
4

Register a new user

Register a new user identity:
const session = await bloque.register('[email protected]', {
  firstName: 'John',
  lastName: 'Doe',
  profile: {
    type: 'individual',
    dateOfBirth: '1990-01-01',
    governmentIdNumber: '123456789',
  },
});

console.log('User registered:', session.urn);
// "did:bloque:your-origin:[email protected]"
The register() method:
  • Creates a new identity with the given alias (email, phone, or custom ID)
  • Returns a session object with access to all API clients
  • Automatically authenticates the user
5

Create a virtual account

Create a virtual account for testing:
const virtualAccount = await session.accounts.virtual.create({
  name: 'Test Account',
  metadata: {
    purpose: 'testing',
  },
});

console.log('Account created:', virtualAccount.urn);
console.log('Status:', virtualAccount.status);
6

Issue a virtual card

Create a virtual card for making payments:
const card = await session.accounts.card.create({
  name: 'My Virtual Card',
  metadata: {
    purpose: 'online-shopping',
  },
});

console.log('Card created:', card.urn);
console.log('Last four digits:', card.lastFour);
console.log('Status:', card.status);
console.log('Details URL:', card.detailsUrl);
The card is now ready to use for transactions!

​
Complete Example

Here’s the full code for reference: 
import { SDK } from '@bloque/sdk';

async function main() {
  // Initialize SDK
  const bloque = new SDK({
    origin: process.env.BLOQUE_ORIGIN!,
    auth: {
      type: 'apiKey',
      apiKey: process.env.BLOQUE_API_KEY!,
    },
    mode: 'sandbox',
  });

  // Register a new user
  const session = await bloque.register('[email protected]', {
    firstName: 'John',
    lastName: 'Doe',
    profile: {
      type: 'individual',
      dateOfBirth: '1990-01-01',
      governmentIdNumber: '123456789',
    },
  });

  console.log('User registered:', session.urn);

  // Create a virtual account
  const account = await session.accounts.virtual.create({
    name: 'Test Account',
  });

  console.log('Account created:', account.urn);

  // Create a virtual card
  const card = await session.accounts.card.create({
    name: 'My Virtual Card',
  });

  console.log('Card created:', card.urn);
  console.log('Last four:', card.lastFour);
}

main().catch(console.error);

​
Connecting to Existing Users

Once a user is registered, use connect() instead of register(): 
const bloque = new SDK({
  origin: process.env.BLOQUE_ORIGIN!,
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'sandbox',
});

// Connect to existing user
const session = await bloque.connect('[email protected]');

// Now you can use all the same APIs
const cards = await session.accounts.card.list();
console.log(`User has ${cards.accounts.length} cards`);

​
Next Steps

Explore Accounts

Learn about card accounts, Polygon wallets, and more

Authentication

Understand API key and JWT authentication

Swap & Exchange

Add currency exchange and swap functionality

API Reference

Explore the complete API documentation

​
Common Issues

Make sure your API key is correct and has the proper format. Check that:
  • The API key is set in your environment variables
  • There are no extra spaces or quotes in the .env file
  • You’re using the correct key for sandbox vs production
The alias (email/phone) is already registered. Use connect() instead of register():
const session = await bloque.connect('[email protected]');
Check your internet connection and firewall settings. If you’re behind a corporate proxy, you may need to configure proxy settings.
Ensure you’ve installed all dependencies:
npm install @bloque/sdk
And that you’re using Node.js 22 or higher.

Build docs developers (and LLMs) love

Get started for freeTalk to us