> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oumla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with Oumla API in 5 minutes

export const apiUrl = 'https://sandbox.oumla.com';

export const apiKeysUrl = 'https://dashboard.oumla.com/dashboard/apikeys';

export const dashboardUrl = 'https://dashboard.oumla.com';

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:

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="box" href="/sdk-reference/introduction">
    **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.
  </Card>

  <Card title="REST API" icon="code" href="/api-reference/introduction">
    **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.
  </Card>
</CardGroup>

<Tip>
  **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.
</Tip>

## Understanding the Oumla Model

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

<CardGroup cols={1}>
  <Card title="Profile" icon="user">
    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).
  </Card>

  <Card title="Wallet" icon="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.
  </Card>

  <Card title="Address" icon="map-pin">
    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).
  </Card>
</CardGroup>

The relationship flows: **Profile → Wallet → Address → Transaction**

<Tip>
  **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.
</Tip>

## Prerequisites

Before you begin, make sure you have:

<CardGroup cols={2}>
  <Card title="Create an Account" icon="user-plus" href={dashboardUrl}>
    Sign up at the Oumla dashboard to get started
  </Card>

  <Card title="Get Your API Key" icon="key" href={apiKeysUrl}>
    Generate your API key from the dashboard
  </Card>
</CardGroup>

<Info>
  All API requests require authentication via the `x-api-key` header. See the [Authentication](/guides/authentication) guide for details.
</Info>

## Choose Your Integration Method

### Option 1: Use the TypeScript SDK (Recommended)

The SDK provides a type-safe, easy-to-use interface:

```bash theme={null}
npm install @oumla/sdk
```

```javascript theme={null}
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:

```bash theme={null}
# 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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript (SDK) theme={null}
  // 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);
  ```

  ```javascript JavaScript (REST API) theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

<Accordion title="Expected Response">
  ```json theme={null}
  {
    "message": "Profile created",
    "data": {
      "reference": "user-123",
      "type": "User"
    },
    "success": true,
    "status": 201
  }
  ```
</Accordion>

## 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:

<Tip>
  The same workflow can be achieved using direct REST API calls. See the [API Reference](/api-reference/introduction) for endpoint details.
</Tip>

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Explore Features" icon="compass" href="/api-reference/introduction">
    Discover wallets, transactions, smart contracts, and tokenization capabilities
  </Card>

  <Card title="View All Endpoints" icon="code" href="/api-reference/introduction">
    Browse the complete API reference with interactive playground
  </Card>

  <Card title="Learn About Security" icon="shield" href="/guides/security">
    Understand Oumla's hybrid key management model
  </Card>

  <Card title="See Use Cases" icon="lightbulb" href="/guides/use-cases">
    Get inspired by what you can build with Oumla
  </Card>
</CardGroup>

<Tip>
  **Pro Tip**: Use the interactive API playground in the [API Reference](/api-reference/introduction) to test endpoints with your API key before integrating into your application.
</Tip>