# Sarna Technologies API

> Broker-dealer and clearing firm infrastructure API providing trading, risk management, account management, and market data services via REST and gRPC.

## Authentication
- Sandbox: Bearer token (`Authorization: Bearer <token>`)
- Production: HMAC-SHA256 signed requests
- Admin endpoints (`/admin/*`) require separate permission grant

## Base URLs
- Sandbox: https://api.sandbox.sarna.io
- Production: https://api.sarna.io

## Quick Start: Place an Order

1. GET /quote/{Symbol} — Get current quote
2. POST /orders — Submit order
3. POST /positions — Check positions

## Common Workflows

1. Get account balances: GET /balances/account/id/{AccountId}
2. Get buying power: POST /buying-power
3. Search symbols: POST /search
4. Get open positions: POST /positions
5. Get trade history: POST /trade
6. Get commission estimate: POST /commissions/estimate-maximum-commission-charge
7. Get order execution logs: GET /order-execution-logs/accounts/{AccountNumbers}
8. Get securities data: GET /securities-master/equities
9. Get option chain: GET /chain-quotes/{UnderlyingSymbol}
10. Create session: POST /sessions

## API Domains
- Accounts: Account management, subaccounts, activity, ABA accounts, ACH transfers
- Orders: Order entry and execution logs
- Positions: Open and closed positions
- Market Data: Quotes, option chains, expirations
- Balances: Account balances and buying power
- Trades: Trade execution
- Risk: Risk monitoring alerts
- Commissions: Commission calculations and estimates
- Sessions: Session management and authentication
- Search: Symbol and security search
- Admin: Administrative operations (requires separate permission grant)

## Resources
- OpenAPI 3.1 Spec: https://developer.sarna.io/for-agents/rest/openapi.json
- Agent Quickstart: https://developer.sarna.io/for-agents/quickstart
- Human Guides: https://developer.sarna.io/guides
- SDKs: https://developer.sarna.io/sdks

## Common Errors
- 401 Unauthorized: Check Authorization header format and token validity
- 429 Rate Limited: Implement exponential backoff; check Retry-After header
- 400 INSUFFICIENT_BUYING_POWER: Check account balance before placing orders
- 403 Forbidden: Admin endpoints require separate permission grant

## Response Handling
1. Check `Errors` array — if non-empty, operation failed
2. Check `Warnings` array — log for user attention
3. Check `HasData` — if false, no results found
4. Process business data fields

## Data Conventions
- All field names use PascalCase (e.g., AccountId, OrderId)
- Financial amounts: negative = debit (money out), positive = credit (money in)
- All timestamps are UTC (ISO 8601)
- Enum value 0 is always undefined/invalid — never use as input