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

# SDK Reference

> Complete TypeScript SDK reference for Oumla API

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

The Oumla TypeScript SDK provides a type-safe, easy-to-use interface for interacting with the Oumla API. This reference documents all available SDK methods organized by resource.

<Info>
  **Two Ways to Use Oumla**: You can interact with Oumla either through our **TypeScript SDK** (documented here) or through **direct REST API calls** (see [API Reference](/api-reference/introduction)). Both methods provide the same functionality - choose the one that best fits your project. The SDK is recommended for TypeScript/JavaScript projects as it provides type safety and better developer experience.
</Info>

## Installation

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

or

```bash theme={null}
yarn add @oumla/sdk
```

or

```bash theme={null}
pnpm add @oumla/sdk
```

## Quick Start

```typescript theme={null}
import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';

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

<Info>
  Get your API key from the <a href={apiKeysUrl} target="_blank" rel="noopener noreferrer">dashboard</a>.
</Info>

## SDK Resources

The SDK is organized into the following resource modules:

<CardGroup cols={2}>
  <Card title="Profiles" icon="user" href="/sdk-reference/profiles">
    Create and manage user profiles (User, Department, Merchant)
  </Card>

  <Card title="Wallets" icon="wallet" href="/sdk-reference/wallets">
    Generate and manage wallets for profiles and organizations
  </Card>

  <Card title="Addresses" icon="map-pin" href="/sdk-reference/addresses">
    Generate addresses for Bitcoin and Ethereum networks
  </Card>

  <Card title="Transactions" icon="clock-rotate-left" href="/sdk-reference/transactions">
    Query transaction history by address, wallet, profile, or organization
  </Card>

  <Card title="Portfolio" icon="coins" href="/sdk-reference/portfolio">
    View assets and native balances across addresses
  </Card>

  <Card title="Withdrawals" icon="arrow-up-from-bracket" href="/sdk-reference/withdrawals">
    Create and execute withdrawal requests
  </Card>

  <Card title="Tokenization" icon="sparkles" href="/sdk-reference/tokenization">
    Create collections, mint tokens, and manage NFTs (ERC-721, ERC-1155)
  </Card>

  <Card title="Contract Templates" icon="file-code" href="/sdk-reference/contract-templates">
    Manage smart contract templates and deploy contracts
  </Card>

  <Card title="Deployed Contracts" icon="code" href="/sdk-reference/deployed-contracts">
    Manage deployed contracts and contract ABIs
  </Card>

  <Card title="Contract Interactions" icon="code-branch" href="/sdk-reference/contract-interactions">
    Call read and write functions on deployed contracts
  </Card>

  <Card title="Workflows" icon="hourglass" href="/sdk-reference/workflows">
    Track async workflow status for long-running operations
  </Card>
</CardGroup>

## Type Safety

The SDK provides full TypeScript support with comprehensive type definitions:

```typescript theme={null}
import type { CreateProfileRequest, CreateProfileResponse } from '@oumla/sdk';

const request: CreateProfileRequest = {
  reference: 'user-123',
  type: 'User'
};

const response: CreateProfileResponse = await client.profiles.createProfile(request);
```

## Error Handling

All SDK methods throw typed errors that you can catch and handle:

```typescript theme={null}
import { OumlaSdkApiError } from '@oumla/sdk';

try {
  const profile = await client.profiles.createProfile({ reference: 'user-123', type: 'User' });
} catch (error) {
  if (error instanceof OumlaSdkApiError) {
    console.error('API Error:', error.statusCode, error.message);
    // Handle specific error codes
    if (error.statusCode === 401) {
      // Authentication error
    }
  }
}
```

## Environments

The SDK supports multiple environments:

```typescript theme={null}
import { OumlaSdkApiEnvironment } from '@oumla/sdk';

// Sandbox environment (for testing)
const sandboxClient = new OumlaSdkApiClient({
  environment: OumlaSdkApiEnvironment.Sandbox,
  apiKey: 'your-sandbox-api-key'
});

// Production environment
const productionClient = new OumlaSdkApiClient({
  environment: OumlaSdkApiEnvironment.Production,
  apiKey: 'your-production-api-key'
});

// Custom base URL
const customClient = new OumlaSdkApiClient({
  baseUrl: 'https://custom-api.example.com',
  apiKey: 'your-api-key'
});
```

## Request Options

All SDK methods accept optional request options:

```typescript theme={null}
const profile = await client.profiles.createProfile(
  { reference: 'user-123', type: 'User' },
  {
    timeoutInSeconds: 30,
    maxRetries: 3,
    apiKey: 'override-api-key', // Override default API key
    headers: { 'Custom-Header': 'value' }
  }
);
```

## Next Steps

* Check out the [Quick Start Guide](/guides/quickstart) for a complete walkthrough
* Explore [Workflow Guides](/guides/workflows/tokenization) for common use cases
* Review the [API Reference](/api-reference/introduction) for REST API details