Getting Started

Get up and running with the 1HOUSE API in minutes.

Prerequisites

Before you begin, ensure you have:

A 1HOUSE account
API keys for both development and production environments (contact your administrator)
Development environment set up
HTTP client (cURL, Postman, or SDK)

API Keys Are Environment-Specific

Each environment (development and production) requires a separate API key. Your development API key will not work in production, and your production API key will not work in development. Make sure you have both keys and use the correct one for each environment.

Need API Keys?

Contact your administrator or support team to request API keys for both development and production environments.

Quick Start

Obtain API Keys

Request API keys from your administrator for both environments. You'll receive:

Development API Key - For https://api-gateway.dev.1houseglobalservices.com
Production API Key - For https://api-gateway.prod.1houseglobalservices.com
API Key ID and Secret for each
Rate limit tier

Store these securely and separately - they provide access to their respective environments. Never use production keys in development or vice versa.

Create your first user account:

// Development
const DEV_API_URL = 'https://api-gateway.dev.1houseglobalservices.com';
const DEV_API_KEY = 'your-development-api-key';

// Production
const PROD_API_URL = 'https://api-gateway.prod.1houseglobalservices.com';
const PROD_API_KEY = 'your-production-api-key';

// Use appropriate URL and key based on environment
const apiUrl = process.env.NODE_ENV === 'production' ? PROD_API_URL : DEV_API_URL;
const apiKey = process.env.NODE_ENV === 'production' ? PROD_API_KEY : DEV_API_KEY;

const response = await fetch(`${apiUrl}/v1/auth/signup`, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePass123!',
    firstName: 'John',
    lastName: 'Doe'
  })
});

const { data } = await response.json();
console.log('Access Token:', data.accessToken);

import requests
import os

# Development
DEV_API_URL = 'https://api-gateway.dev.1houseglobalservices.com'
DEV_API_KEY = 'your-development-api-key'

# Production
PROD_API_URL = 'https://api-gateway.prod.1houseglobalservices.com'
PROD_API_KEY = 'your-production-api-key'

# Use appropriate URL and key based on environment
api_url = PROD_API_URL if os.getenv('ENVIRONMENT') == 'production' else DEV_API_URL
api_key = PROD_API_KEY if os.getenv('ENVIRONMENT') == 'production' else DEV_API_KEY

response = requests.post(
    f'{api_url}/v1/auth/signup',
    headers={
        'X-API-Key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'email': 'user@example.com',
        'password': 'SecurePass123!',
        'firstName': 'John',
        'lastName': 'Doe'
    }
)

data = response.json()
print('Access Token:', data['data']['accessToken'])

# Development
curl -X POST https://api-gateway.dev.1houseglobalservices.com/v1/auth/signup \
  -H "X-API-Key: your-development-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "firstName": "John",
    "lastName": "Doe"
  }'

# Production
curl -X POST https://api-gateway.prod.1houseglobalservices.com/v1/auth/signup \
  -H "X-API-Key: your-production-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "firstName": "John",
    "lastName": "Doe"
  }'

Make Your First API Call

Use the access token to fetch the user profile:

// Use the same API URL and key from signup
const profileResponse = await fetch(`${apiUrl}/v1/user/profile`, {
  headers: {
    'X-API-Key': apiKey,
    'Authorization': `Bearer ${accessToken}`
  }
});

const profile = await profileResponse.json();
console.log('User Profile:', profile.data);

Handle Token Refresh

Implement automatic token refresh:

async function makeAuthenticatedRequest(url, options = {}) {
  let token = localStorage.getItem('accessToken');
  
  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'X-API-Key': 'your-api-key',
      'Authorization': `Bearer ${token}`
    }
  });

  // If token expired, refresh and retry
  if (response.status === 401) {
    const refreshToken = localStorage.getItem('refreshToken');
    const refreshResponse = await fetch(`${apiUrl}/v1/auth/refresh-token`, {
      method: 'POST',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ refreshToken })
    });

    const { data } = await refreshResponse.json();
    localStorage.setItem('accessToken', data.accessToken);
    localStorage.setItem('refreshToken', data.refreshToken);

    // Retry original request
    return makeAuthenticatedRequest(url, options);
  }

  return response;
}

Response Structure

All API responses follow a standardized format:

{
  "success": true,
  "status": 200,
  "message": "Operation successful",
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2025-10-21T12:00:00.000Z",
    "version": "v1"
  }
}

{
  "success": false,
  "status": 400,
  "message": "Validation error",
  "error": "Invalid email format",
  "meta": {
    "timestamp": "2025-10-21T12:00:00.000Z",
    "version": "v1"
  }
}

{
  "success": true,
  "status": 200,
  "message": "Results retrieved",
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  },
  "meta": {
    "timestamp": "2025-10-21T12:00:00.000Z",
    "version": "v1"
  }
}

Common HTTP Status Codes

Status Code	Meaning	When It Occurs
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request data
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Error Handling

Error Handling Best Practice

Always implement proper error handling to gracefully manage API failures and provide clear feedback to users.

Example Error Handler

async function handleApiError(response) {
  if (!response.ok) {
    const error = await response.json();
    
    switch (response.status) {
      case 400:
        throw new Error(`Validation Error: ${error.error}`);
      case 401:
        // Redirect to login
        window.location.href = '/login';
        break;
      case 403:
        throw new Error('Insufficient permissions');
      case 404:
        throw new Error('Resource not found');
      case 429:
        throw new Error('Rate limit exceeded. Please wait.');
      case 500:
        throw new Error('Server error. Please try again later.');
      default:
        throw new Error('An unexpected error occurred');
    }
  }
  
  return response.json();
}

// Usage
try {
  const data = await handleApiError(response);
  // Process data
} catch (error) {
  console.error(error.message);
  // Show error to user
}

Rate Limits

Rate Limiting

All API keys have rate limits based on their tier. Monitor your usage and upgrade if needed.

Tier	Requests/Minute	Requests/Hour	Requests/Day
Mobile	60	1,000	20,000
Live Platform	120	5,000	100,000
CRM	300	15,000	300,000
Third Party	60	2,000	40,000
Admin	Unlimited	Unlimited	Unlimited

Rate Limit Headers

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1698765432

Next Steps

Now that you're set up, explore the API:

Authentication - Complete auth documentation
Trading API - Start tracking trades
Education API - Access courses
Community API - Engage with users
Intelligence API - Use AI chatbot

Need Help?

API Reference - Complete endpoint documentation
Support - Contact our team
GitHub - View source code
Status Page - Check API status

Getting Started

On this page