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

# Sandbox Environment

> Core Buildmarkets concepts, data model, API conventions, and sandbox testing with SSN-suffix KYC outcomes and simulated fills and funding.

This page introduces the core concepts, data model, and conventions used throughout the Buildmarkets API. Reading this before diving into feature-specific guides will save you significant time.

## Core concepts

### Partners

You — the company integrating Buildmarkets. Partners authenticate with the API using key pairs (`X-API-Key` / `X-API-Secret`) scoped to their tenant. All accounts, orders, and funding activity created through your API keys are associated with your partner account.

### Accounts

A Buildmarkets **account** represents one end-user brokerage account. Each account holds an identity (KYC data: name, DOB, SSN), contact information (address, phone, email), regulatory disclosures and signed agreements, an investment profile (suitability data), and positions, balances, orders, and funding activity. Accounts are the central resource in the Buildmarkets Wealth API. Almost every other resource — orders, positions, funding — is scoped under `GET /v1/accounts/{accountId}/...`.

### Orders

An **order** is an instruction to buy or sell a security. Buildmarkets supports equity and ETF orders with market, limit, stop, and stop-limit order types. Orders go through a lifecycle of states and generate **executions** (fills) once matched.

### ACH Relationships

An **ACH relationship** links a customer's external bank account to their Buildmarkets brokerage account. It is a prerequisite for funding. Once linked, you can initiate deposits (money into the brokerage account) and withdrawals (money back to the bank).

### Webhooks

**Webhooks** are HTTP callbacks that Buildmarkets fires to your server when significant events occur — an account's KYC status changes, an order is filled, or a deposit settles. Webhooks are the recommended way to stay in sync with state changes rather than polling.

## Data model overview

Partner (you) holds API Keys (credentials) and Accounts\[]. Each Account contains Contact, Identity, Disclosures, Agreements\[], InvestmentProfile, TradingConfigurations, Balances, Positions\[], Orders\[] (each with Executions\[]), ACH Relationships\[], and Funding Activity\[]. Webhooks are partner-level. Market Data is partner-level (not account-scoped). Documents are partner-level plus account-level uploads.

## API conventions

### REST & JSON

The Buildmarkets API is a REST API. All request and response bodies are JSON. Set `Content-Type: application/json` on all requests with a body.

### Authentication

Every request must include two headers:

```
X-API-Key: <your-api-key>
X-API-Secret: <your-api-secret>
```

See Authentication Overview for how to generate and manage API keys.

### IDs

* `accountId` — UUID string, e.g. `"b3f2c9a1-4d5e-4a2f-8b3c-1e2d3f4a5b6c"`
* `orderId` — UUID string
* `achId` — UUID string
* `webhookId` — UUID string

Always store and pass IDs as strings. Do not treat them as integers or attempt to sort them numerically.

### Timestamps

All timestamps are **ISO 8601** strings in UTC, e.g. `"2025-06-01T14:32:00Z"`. When submitting timestamps (e.g., `signed_at` on agreements), use this format.

### Monetary amounts

Dollar amounts (balances, order quantities, transfer amounts) are represented as **decimal strings**, not floating-point numbers. This avoids precision loss on monetary values.

```json theme={"system"}
{ "amount": "1000.00" }
```

### Pagination

List endpoints that return multiple records use **cursor-based pagination**. The response shape is:

```json theme={"system"}
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true
  }
}
```

Pass `cursor=<next_cursor>` as a query parameter to fetch the next page. Use `limit` to control page size.

### Idempotency

For `POST` requests that initiate financial operations (orders, deposits, withdrawals), use the `client_order_id` or equivalent idempotency field to safely retry without duplicate execution.

## Sandbox testing

In the sandbox environment (`https://dev-tapp-api.tappengine.com`), KYC outcomes are controlled by the SSN suffix you provide when creating an account:

| SSN suffix | Outcome         |
| ---------- | --------------- |
| `0001`     | `APPROVED`      |
| `0002`     | `REJECTED`      |
| `0003`     | `MANUAL_REVIEW` |

For example, SSN `111-22-0001` will result in an immediately approved account. All other sandbox behavior (order fills, funding transfers) is also simulated — no real money or real orders are involved.

## Next steps

* Getting Started — Step-by-step guide to your first API call
* Authentication Overview — Generating and managing API keys
* Use Cases — Common integration patterns