Prop-Firm Partner API
Integrate your prop-firm dashboard with A2Z Trader as the trading engine. The API ships in two postures that differ only by who owns the plans & rules — and therefore which scopes a firm is granted. Same authentication, same base, you pick the mode (or mix).
Set 1 — Orchestration
Your system is the source of truth. You define challenge plans, rules, pricing, phases and payouts via the API; A2Z Trader provisions accounts and executes/monitors trading. Broad write scopes.
Base: /api/v1/propfirm
Set 2 — Storefront
A2Z Trader is the source of truth. Plans, groups and risk are configured in the A2Z admin; your dashboard just sells & provisions. Read + constrained-create scopes — safer, faster to onboard.
Base: /api/v1/storefront
Recommendation: default to Storefront; grant Orchestration to technical firms that want full control. The two share one API + auth stack.
Authentication
The API uses OAuth2 client-credentials. A2Z Trader issues your firm a client_id and
client_secret (scoped to your broker tenant). Exchange them for a short-lived bearer token,
then call the endpoints with Authorization: Bearer <token>.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/oauth/token | client-credentials grant → access_token, expires_in, granted scope |
curl -X POST https://api.<platform-domain>/api/v1/oauth/token \
-d grant_type=client_credentials \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET
# → { "access_token": "…", "token_type": "Bearer", "expires_in": 3600, "scope": "catalog:read accounts:provision …" }
403 prop_firm_not_enabled. A call lacking the
required scope receives 403 insufficient_scope.Set 1 — Orchestration API /api/v1/propfirm
Full control. Your platform owns challenge plans, accounts, rules and payouts.
Challenge plans
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /plans | plans:read | List challenge plans |
| POST | /plans | plans:write | Create a plan (size, target, drawdown, phases, price) |
| GET | /plans/{id} | plans:read | Plan detail |
| PATCH | /plans/{id} | plans:write | Update a plan |
| DELETE | /plans/{id} | plans:write | Retire a plan |
Accounts
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /accounts | accounts:write | Provision an evaluation account (plan + trader) |
| GET | /accounts | accounts:read | List accounts (filter by status/phase/plan) |
| GET | /accounts/{id} | accounts:read | State: equity, drawdown used, target progress, phase |
| GET | /accounts/{id}/metrics | accounts:read | Metrics snapshot |
| POST | /accounts/{id}/phase | accounts:write | Advance phase (eval → funded) |
| POST | /accounts/{id}/reset | accounts:write | Reset the evaluation |
| POST | /accounts/{id}/balance | balance:write | Deposit / withdraw / credit / adjust |
| DELETE | /accounts/{id} | accounts:write | Close / archive |
| POST | /accounts/{id}/sso | accounts:read | Mint an embedded-terminal SSO token |
Payouts
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /accounts/{id}/payouts | payouts:write | Trigger a payout (profit split) |
| GET | /payouts | payouts:read | List payouts |
| GET | /payouts/{id} | payouts:read | Payout detail |
Set 2 — Storefront API /api/v1/storefront
Constrained / read posture. A2Z Trader owns the plans & rules; you sell and provision against them.
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /catalog | catalog:read | List A2Z-configured plans (read-only) |
| GET | /catalog/{id} | catalog:read | Plan detail (rules, price) |
| POST | /accounts | accounts:provision | Provision against a plan by planId (server applies the plan's rules) |
| GET | /accounts/{id} | accounts:read | State: phase, status, target progress, drawdown |
| GET | /accounts/{id}/metrics | metrics:read | Metrics snapshot |
| POST | /accounts/{id}/sso | accounts:read | Embedded-terminal SSO token |
| POST | /accounts/{id}/payout-request | payouts:request | Request a payout → pending internal approval (no direct execution) |
Provisioning partner clients (broker admin)
A broker admin issues credentials to a firm from the admin API:
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/admin/partner-clients | Admin | Create a partner client_id/secret + granted scopes (secret shown once) |
Webhooks
Subscribe to HMAC-signed, retried event callbacks (scope events:subscribe):
account.created · account.breached · target.reached ·
phase.passed · phase.failed · drawdown.warning ·
order.opened · order.closed · equity.threshold ·
payout.requested · payout.processed
Scopes reference
Set 1 (Orchestration): plans:read plans:write accounts:read accounts:write balance:write payouts:read payouts:write users:write events:subscribe
Set 2 (Storefront): catalog:read accounts:provision accounts:read metrics:read payouts:request events:subscribe