Boursa Docs

Appearance

Getting started ​

Boursa lets your application open EGX brokerage accounts, fund them, and trade equities and money-market funds through one REST API. This page takes you from zero to a first order in the sandbox.

1. Get sandbox credentials ​

The sandbox runs on simulated money against a production-grade backend. It is reachable at:

  • API: https://sandbox.boursa.sh
  • Console: https://console.boursa.sh

Your tenant credentials are an api_key (Bearer auth) and a signing_secret (HMAC signature on money endpoints). In local development the seeded demo tenant prints them once in the boot log; on the hosted sandbox they're provisioned for you.

2. The shape of an integration ​

A complete user journey is five steps. Each maps to a guide:

  1. Onboarding — create a KYC application, upload the national-ID photos, submit. The brokerage reviews and opens the account, returning an investor_id.
  2. Suitability — record the investor's suitability answers and risk acknowledgment (a regulatory gate before trading).
  3. Funding — deposit cash; it settles into the investor's balance.
  4. Trading — place equity orders and fund subscriptions.
  5. Portfolio — read balances, positions, performance, and statements.

Until the brokerage approves the account, there is no investor_id and no money can move — your users can browse market data, but funding and trading are gated. This mirrors how the platform enforces it server-side.

3. Read something (no signature needed) ​

Read endpoints need only the Bearer key:

bash
curl https://sandbox.boursa.sh/v1/instruments \
  -H "Authorization: Bearer $BOURSA_API_KEY"
bash
curl https://sandbox.boursa.sh/v1/clock \
  -H "Authorization: Bearer $BOURSA_API_KEY"
# {"timestamp":"2026-06-14T11:00:00+03:00","is_open":true,
#  "next_open":"2026-06-15T10:00:00+03:00","next_close":"2026-06-14T14:30:00+03:00"}

4. Place an order (signed) ​

Money endpoints (POST /v1/orders, /v1/fund-orders, /v1/transfers, DELETE /v1/orders/{id}) carry an HMAC signature and an idempotency key. See Authentication for how to compute the signature.

bash
curl -X POST https://sandbox.boursa.sh/v1/orders \
  -H "Authorization: Bearer $BOURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Boursa-Timestamp: $TS" \
  -H "X-Boursa-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
        "investor_id": "inv_…",
        "symbol": "COMI",
        "side": "buy",
        "type": "market",
        "qty": 10,
        "time_in_force": "day"
      }'

The response is an order object with both the internal state and the Alpaca-aligned status.

5. Fast-forward the sandbox clock ​

EGX trades Sun–Thu, 10:00–14:30 Africa/Cairo. The sandbox runs on a simulated clock you can advance so you don't have to wait for market hours:

bash
curl -X POST https://sandbox.boursa.sh/admin/sandbox/clock-advance \
  -H "X-Admin-Key: $BOURSA_ADMIN_KEY" \
  -d '{"hours": 2}'

When the session is open, market orders fill immediately and marketable limit orders fill at the live price; a limit away from the market rests until the price reaches it (or, for gtc, across sessions). See Order lifecycle.

Next ​

Embedded investing infrastructure for the Egyptian Exchange. Sandbox runs on simulated money.

© Boursa