# Getting Started with Broker API

> Build and test a complete embedded-investing workflow in the MyStocks sandbox.

This guide takes you from a sandbox credential to a testable customer-investing workflow.

## Before you start

- Create a partner session in the [sandbox portal](/partners/sandbox).
- Keep the sandbox key server-side.
- Review the source-preview [TypeScript or Python SDK](/partners/docs/sdks-tools), or use `curl`.
- Read [authentication](/partners/docs/auth), [errors](/partners/docs/errors), and [idempotency](/partners/docs/concepts).

## Build the golden path

1. Create a sub-account with an idempotent `POST /users` request.
2. Deposit virtual funds with a unique `Idempotency-Key`.
3. Optionally assert KYC to test the production-style flow. Normal sandbox trading does not require KYC; production requires the applicable verification before trading.
4. Request a quote immediately before the trade.
5. Place the trade with the matching `quoteId` and the same idempotency key if retrying.
6. Consume the order, execution, wallet, and portfolio state through REST, [webhooks](/partners/docs/webhooks), or [SSE](/partners/docs/sse-events).
7. Run the reconciliation workflow before requesting production access.

The complete copyable workflow is in the [Broker API quickstart](/partners/docs/quickstart). Use the [API Tester](/partners/docs/api-tester) to run individual operations and the [API Reference](/partners/docs/api-reference) for schemas.

## Production transition

Sandbox success does not grant production access. Attach evidence for concurrency/idempotency, webhook retry handling, failover, reconciliation, security controls, and data governance through [Going Live](/partners/docs/going-live).

## Verify each handoff

Open the [guided sandbox workflow](/partners/docs/api-tester?workflow=broker). Create a synthetic customer, copy the returned identity, add virtual USD funds and read the starting wallet. Request a fresh quote and use **Prepare trade** to carry its identifier into the trade request. Review each request before sending it.

The deterministic simulator provides a separate lifecycle path: pending, partial fill, fill and settlement. Compare executions, available and reserved cash, holdings and transaction entries after each transition. Cancellation and rejection should release reservations; a successful submission does not prove settlement.

| Failure                     | Recovery                                                             |
| --------------------------- | -------------------------------------------------------------------- |
| Expired quote               | Request a fresh quote before creating a new trade.                   |
| Response lost after a write | Retry the identical request with its original idempotency key.       |
| Restricted customer         | Inspect eligibility and KYC status; do not bypass production policy. |
| Rate limit or maintenance   | Respect `Retry-After` and retry with bounded backoff.                |

Download the tester report for request evidence, then verify webhook/SSE delivery in your receiving service. The report does not certify real provider execution. Continue with [Going Live](/partners/docs/going-live).
