# Public API

The Braiins Hashpower API provides programmatic access to market data and trading functionality. The full interactive API reference is available in Scalar at [hashpower.braiins.com/api](https://hashpower.braiins.com/api).

## Overview

The Braiins Hashpower API is a RESTful API that allows you to:

- Access real-time market data (order book, trades, charts)
- Manage bids (create, modify, cancel)
- View account information and balances
- Monitor bid status and history
- Access transaction records

### API Documentation

Interactive API documentation generated from the public `OpenAPI` specification is available in Scalar:

**[https://hashpower.braiins.com/api](https://hashpower.braiins.com/api)**

The Scalar API reference provides:

- Complete endpoint descriptions, including access requirements and rate limits
- Request parameters and request/response schemas
- API token authentication
- A built-in **Test Request** client that calls the `/v1` API in the same Hashpower environment

Scalar keeps the API token you enter in browser storage for this site. Remove the saved authentication after testing on a shared browser.

## Authentication

### API Token

Authenticated endpoints require an API token passed via the `apikey` header:

```
apikey: your-api-token-here
```

### Token Types

| **Token Type**  | **Access Level**                               |
| --------------- | ---------------------------------------------- |
| Owner Token     | Full access to all endpoints including trading |
| Read-only Token | Access to market data and account viewing only |

### Obtaining API Tokens

1. Visit [hashpower.braiins.com](https://hashpower.braiins.com)
2. Click **Sign Up** and complete registration
3. Your API tokens are displayed after successful registration
4. Store the tokens securely — they are only shown once


Never expose your API tokens in client-side code, public repositories, or logs. Use environment variables or secure secret management.

## Base URL

All API requests should be made to:

```
https://hashpower.braiins.com/v1/
```

### Example Request

```bash
curl -X GET "https://hashpower.braiins.com/v1/spot/orderbook" \
  -H "Content-Type: application/json"
```

## Public Endpoints

Public endpoints do not require authentication and provide market data.

| **Endpoint**      | **Method** | **Description**                                   |
| ----------------- | ---------- | ------------------------------------------------- |
| `/spot/orderbook` | GET        | Current order book with bids and asks             |
| `/spot/trades`    | GET        | Recent trade history                              |
| `/spot/bars`      | GET        | OHLCV candlestick data for charts                 |
| `/spot/stats`     | GET        | Market statistics (volume, best prices, hashrate) |

## Authenticated Endpoints

Authenticated endpoints require the `apikey` header.

### Account

| **Endpoint**                    | **Method** | **Description**                              |
| ------------------------------- | ---------- | -------------------------------------------- |
| `/account/balance`              | GET        | Current balance (available, reserved, total) |
| `/account/transaction`          | GET        | Transaction history                          |
| `/account/transaction/on-chain` | GET        | List on-chain account transactions           |

### Market

| **Endpoint**     | **Method** | **Description**                                 |
| ---------------- | ---------- | ----------------------------------------------- |
| `/spot/settings` | GET        | Market configuration (tick size, limits, units) |
| `/spot/fee`      | GET        | Current fee structure                           |

### Bid Management

| **Endpoint**                    | **Method** | **Description**                       |
| ------------------------------- | ---------- | ------------------------------------- |
| `/spot/bid`                     | GET        | List all bids (historical and active) |
| `/spot/bid`                     | POST       | Create a new bid                      |
| `/spot/bid`                     | PUT        | Update an existing bid                |
| `/spot/bid`                     | DELETE     | Cancel a bid                          |
| `/spot/bid/current`             | GET        | List active bids only                 |
| `/spot/bid/detail/{order_id}`   | GET        | Get detailed bid information          |
| `/spot/bid/speed/{order_id}`    | GET        | Get speed history time series         |
| `/spot/bid/delivery/{order_id}` | GET        | Get delivery history time series      |

For complete endpoint details, request/response schemas, and interactive testing, see the [Scalar API reference](https://hashpower.braiins.com/api).

## Error Handling

### HTTP Status Codes

| **Code** | **Description**                                                     |
| -------- | ------------------------------------------------------------------- |
| 200      | Success                                                             |
| 400      | Bad Request — Invalid parameters                                    |
| 401      | Unauthorized — Invalid or missing API token                         |
| 403      | Forbidden — Insufficient permissions or bid belongs to another user |
| 404      | Not Found — Resource doesn't exist                                  |
| 429      | Too Many Requests — Rate limit exceeded                             |
| 500      | Internal Server Error                                               |

### Error Response Format

For some errors (e.g., Bad Request), the error details are returned in the `grpc-message` header:

```
grpc-message: Bid%20duration%20too%20short%20(estimate:%209.29,%20limit:%201800)
```

The message is URL-encoded and should be decoded to get the human-readable error description.

## Best Practices

1. **Check `/spot/settings` first**: Understand pricing units, limits, and cooldowns before placing bids
2. **Cache market data**: Order book and trades update frequently; cache appropriately
3. **Handle errors gracefully**: Implement retry logic with exponential backoff
4. **Validate inputs client-side**: Prevent unnecessary API calls with invalid data
5. **Monitor your rate limits**: Track usage to avoid hitting limits
6. **Secure your tokens**: Use environment variables, never hardcode
7. **Use `cl_order_id`**: Assign your own IDs to bids for easier tracking and idempotency


---

Was this helpful?

Yes, thanks!Sort of, thanks!Not really

Talk to us!