Skip to main content
Oumla enables developers to easily build on top of blockchains. You don’t need to learn complex, low-level Blockchain-specific APIs. By using our API, you can accelerate your time to market and minimize security concerns.

​
Two Ways to Use Oumla

Oumla provides two ways to interact with the API:

TypeScript SDK

Recommended for most developers. Use our official TypeScript SDK for type-safe, easy-to-use methods. The SDK handles authentication, request formatting, and error handling automatically.

REST API

Direct HTTP calls. Make direct REST API calls to our endpoints using any HTTP client. Perfect for non-TypeScript projects or when you need full control over requests.
Which should I use? If you’re building in TypeScript/JavaScript, we recommend starting with the SDK for a better developer experience. Both methods provide the same functionality and use the same API endpoints under the hood.

​
Understanding the Oumla Model

Before diving in, it’s helpful to understand how Oumla organizes resources:

Profile

A Profile represents a user, department, or merchant in your system. Profiles are the foundation for all other resources. Each profile has a unique reference identifier and a type (User, Department, or Merchant).

Wallet

A Wallet is associated with a profile and a specific blockchain network (BTC, ETH, etc.). Wallets manage addresses and enable transactions on that network.

Address

An Address belongs to a wallet and is used to send and receive funds on a specific blockchain. Each address is unique to a network (BTC addresses differ from ETH addresses).
The relationship flows: Profile → Wallet → Address → Transaction
Address V2: The V2 address generation endpoint (/api/v2/addresses/generate) automatically creates a wallet if one doesn’t exist, simplifying the workflow. This is the recommended approach for most use cases.

​
Prerequisites

Before you begin, make sure you have:

Create an Account

Sign up at the Oumla dashboard to get started

Get Your API Key

Generate your API key from the dashboard
All API requests require authentication via the x-api-key header. See the Authentication guide for details.

​
Choose Your Integration Method

The SDK provides a type-safe, easy-to-use interface: 
npm install @oumla/sdk

import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';

const client = new OumlaSdkApiClient({
  environment: OumlaSdkApiEnvironment.Sandbox,
  apiKey: 'your-api-key-here'
});

​
Option 2: Use Direct REST API Calls

Make HTTP requests directly to our API endpoints: 
# No installation needed - use any HTTP client
curl -X POST "https://sandbox.oumla.com/api/v1/profiles" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"reference": "user-123", "type": "User"}'

​
Make Your First API Call

Let’s create a user profile - the foundation for wallets and transactions: 
curl -X POST "https://sandbox.oumla.com/api/v1/profiles" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "user-123",
    "type": "User"
  }'

{
  "message": "Profile created",
  "data": {
    "reference": "user-123",
    "type": "User"
  },
  "success": true,
  "status": 201
}

​
Complete Workflow Example

Here’s a complete example using the SDK that creates a profile, generates an address (which auto-creates a wallet), and checks the balance:
The same workflow can be achieved using direct REST API calls. See the API Reference for endpoint details.
import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';

const client = new OumlaSdkApiClient({
  environment: OumlaSdkApiEnvironment.Sandbox,
  apiKey: 'your-api-key-here'
});

async function completeWorkflow() {
  try {
    // Step 1: Create a profile
    const profile = await client.profiles.createProfile({
      reference: 'user-123',
      type: 'User'
    });
    console.log('Profile created:', profile);

    // Step 2: Get available networks
    const networks = await client.networks.getNetworks({ skip: 0, take: 50, enabled: true });
    const networkId = networks.data[0].id; // Use appropriate network ID

    // Step 3: Generate an address (V2 auto-creates wallet if needed)
    const address = await client.addresses.createAddressV2({
      reference: 'user-123',
      networkId,
      clientShare: 'your-client-share-here'
    });
    console.log('Address generated:', address.data.address);

    // Step 4: Check native balance
    const balance = await client.portfolio.getNativeBalance({
      address: address.data.address,
      skip: 0,
      take: 50
    });
    console.log('Balance:', balance.data);

  } catch (error) {
    console.error('Error:', error);
  }
}

completeWorkflow();

​
Profile Types

Oumla supports three profile types:
  • User: Individual users in your system
  • Department: Organizational units or departments
  • Merchant: Business entities or merchants
Choose the type that best fits your use case. The reference field should be a unique identifier within your system.

​
Next Steps

Explore Features

Discover wallets, transactions, smart contracts, and tokenization capabilities

View All Endpoints

Browse the complete API reference with interactive playground

Learn About Security

Understand Oumla’s hybrid key management model

See Use Cases

Get inspired by what you can build with Oumla
Pro Tip: Use the interactive API playground in the API Reference to test endpoints with your API key before integrating into your application.