Quick Start

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

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

Option 1: Use the TypeScript SDK (Recommended)

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"
  }'

// Using the TypeScript SDK
import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';

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

const profile = await client.profiles.createProfile({
  reference: 'user-123',
  type: 'User'
});

console.log(profile);

const response = await fetch('https://sandbox.oumla.com/api/v1/profiles', {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'user-123',
    type: 'User'
  })
});

const data = await response.json();
console.log(data);

import requests

headers = {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
}

payload = {
    'reference': 'user-123',
    'type': 'User'
}

response = requests.post('https://sandbox.oumla.com/api/v1/profiles', headers=headers, json=payload)
print(response.json())

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://sandbox.oumla.com/api/v1/profiles"

    payload := map[string]string{
        "reference": "user-123",
        "type":      "User",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("x-api-key", "your-api-key-here")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Expected Response

{
  "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.networks[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'
    });
    const generatedAddress = address.data.data?.address;
    console.log('Address generated:', generatedAddress);

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

  } 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.

Getting Started

Core Concepts

Workflows

Resources

Two Ways to Use Oumla

TypeScript SDK

REST API

Understanding the Oumla Model

Profile

Wallet

Address

Prerequisites

Create an Account

Get Your API Key

Choose Your Integration Method

Option 1: Use the TypeScript SDK (Recommended)

Option 2: Use Direct REST API Calls

Make Your First API Call

Complete Workflow Example

Profile Types

Next Steps

Explore Features

View All Endpoints

Learn About Security

See Use Cases

​Two Ways to Use Oumla

TypeScript SDK

REST API

​Understanding the Oumla Model

Profile

Wallet

Address

​Prerequisites

Create an Account

Get Your API Key

​Choose Your Integration Method

​Option 1: Use the TypeScript SDK (Recommended)

​Option 2: Use Direct REST API Calls

​Make Your First API Call

​Complete Workflow Example

​Profile Types

​Next Steps

Explore Features

View All Endpoints

Learn About Security

See Use Cases

Two Ways to Use Oumla

Understanding the Oumla Model

Prerequisites

Choose Your Integration Method

Option 1: Use the TypeScript SDK (Recommended)

Option 2: Use Direct REST API Calls

Make Your First API Call

Complete Workflow Example

Profile Types

Next Steps