Skip to main content

​
Prerequisites

Before you begin integrating with the Bluum Finance API, ensure you have:
  • API credentials – An API key and secret pair obtained from your Bluum Finance account dashboard
  • Environment access – Sandbox access is available immediately; production access requires partner approval and compliance verification
  • HTTPS capability – All API requests must be made over HTTPS

View Postman documentation

Explore ready-to-run requests with sample payloads and responses. The collection includes pre-configured authentication and example requests for all endpoints.

​
What you can build

Build embedded investment experiences that let your users manage accounts, trade securities, and handle financial operations seamlessly. The Bluum Finance API provides modular services you can integrate independently or combine for complete investment workflows.

Accounts

Onboard investors with complete identity verification, contact information, and regulatory disclosures. Create and manage investment accounts with full KYC compliance.

Documents

Upload and manage KYC documents with automated status tracking. Streamline compliance workflows with document verification and review capabilities.

Trading

Place, monitor, and manage equity and cryptocurrency orders. Support market, limit, and other order types with real-time status updates.

Wallet

Enable deposits, withdrawals, and comprehensive transaction history. Support both fiat and cryptocurrency funding methods with full audit trails.

Assets

Query tradable instruments and filter by asset class, exchange, or other criteria. Access real-time asset information for trading decisions.

Positions

Monitor account positions and holdings across all asset classes. Track portfolio performance and exposure in real-time.

​
Base URLs

Choose the appropriate environment based on your integration stage. All API endpoints are versioned under the /v1 path.

Sandbox

https://sandbox.api.bluum.finance/v1Use for development, testing, and QA workflows. Sandbox data resets nightly at midnight UTC, providing a clean testing environment. All sandbox accounts and transactions are simulated and do not involve real funds or securities.
Start with the sandbox environment to test your integration without affecting production data or requiring compliance approval.

Production

https://api.bluum.finance/v1Production environment for live integrations. Access requires partner approval and completed compliance verification. All operations in production involve real accounts, funds, and securities.
Production credentials provide access to real financial operations. Store credentials securely and never commit them to version control.

​
Authentication

All API requests require HTTP Basic Authentication. Use your API key as the username and your API secret as the password. Base64 encode the string API_KEY:API_SECRET and include it in the Authorization header.
cURL
curl -X GET 'https://sandbox.api.bluum.finance/v1/accounts' \
  -H 'Authorization: Basic '$(echo -n 'YOUR_API_KEY:YOUR_API_SECRET' | base64) \
  -H 'Content-Type: application/json'
Node.js
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

const response = await fetch('https://sandbox.api.bluum.finance/v1/accounts', {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
});
Python
import requests
import base64

api_key = 'YOUR_API_KEY'
api_secret = 'YOUR_API_SECRET'
credentials = base64.b64encode(f'{api_key}:{api_secret}'.encode()).decode()

response = requests.get(
    'https://sandbox.api.bluum.finance/v1/accounts',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    }
)
In Postman, set apiKey and apiSecret variables in your environment. The collection automatically populates the Authorization header using these variables.

​
Headers

​
Authorization
string
required
HTTP Basic Authentication header. Format: Basic <base64_encoded_credentials> where credentials are API_KEY:API_SECRET encoded in Base64. All requests require this header.
​
Content-Type
string
Required for POST and PUT requests. Use application/json for JSON payloads. Use multipart/form-data for document upload endpoints.

​
Rate limits

Rate limits are enforced per API key pair to ensure fair usage and system stability. Limits apply to all endpoints and are calculated on a per-second basis.
  • Sandbox: 10 requests per second per key pair
  • Production: 25 requests per second per key pair
Exceeding rate limits returns a 429 Too Many Requests response. Always check the Retry-After header value (in seconds) before retrying the request.

​
Handling rate limits

When you receive a 429 response, implement exponential backoff with jitter to avoid overwhelming the API: 
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
      const delay = retryAfter * 1000 * Math.pow(2, attempt) + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}
Monitor your request rate and implement client-side throttling to stay within limits. Consider batching operations when possible to reduce the number of requests.

​
Error model

All error responses follow a consistent ErrorResponse schema and return appropriate HTTP status codes. Error responses include a custom error code for programmatic handling and a human-readable message. 
{
  "code": "BLUM-400-001",
  "message": "Invalid quantity. Must be a positive integer."
}

​
Common error codes

The API uses structured error codes following the pattern BLUM-{HTTP_STATUS}-{ERROR_NUMBER}:
  • BLUM-400-* – Bad request errors (validation failures, malformed requests)
  • BLUM-401-* – Authentication errors (missing or invalid credentials)
  • BLUM-404-* – Not found errors (resource doesn’t exist)
  • BLUM-429-* – Rate limit errors (too many requests)

​
Troubleshooting errors

If you receive a 401 Unauthorized response:
  • Verify your API key and secret are correct
  • Ensure credentials are Base64 encoded properly
  • Check that the Authorization header format is Basic <encoded_credentials>
  • Confirm your API key has access to the requested environment (sandbox vs production)
For 400 Bad Request responses:
  • Review the error message for specific field validation issues
  • Check that required fields are present in your request
  • Verify data types match the expected schema (strings, numbers, dates)
  • Ensure date formats follow ISO 8601 (e.g., 2025-10-17T18:00:00Z)
When receiving 404 Not Found:
  • Verify the resource ID exists in your account
  • Check that you’re using the correct endpoint path
  • Ensure the resource belongs to your API key’s account scope
  • Confirm you’re querying the correct environment (sandbox vs production)

​
Response format

All API responses are returned as JSON with UTF-8 encoding. Successful responses include the requested data in the response body, while error responses follow the ErrorResponse schema.

​
Response structure

  • Content-Type: All responses use application/json
  • Character encoding: UTF-8
  • Date formats: ISO 8601 format (e.g., 2025-10-17T18:00:00Z)
  • Numeric values: Decimal numbers are represented as strings to preserve precision (e.g., "175.00" for prices)
  • UUIDs: Resource identifiers use UUID v4 format (e.g., acc_a1b2c3d4e5f6g7h8)

​
HTTP status codes

The API uses standard HTTP status codes to indicate request outcomes:
  • 200 OK – Successful GET, PUT, or DELETE request
  • 201 Created – Resource successfully created (POST requests)
  • 400 Bad Request – Request validation failed or malformed
  • 401 Unauthorized – Authentication required or invalid
  • 404 Not Found – Requested resource doesn’t exist
  • 429 Too Many Requests – Rate limit exceeded
  • 500 Internal Server Error – Server-side error (contact support)
Always check the HTTP status code before parsing the response body. Even with a 200 status, verify the response structure matches your expectations.