Schwab API
Schwab API is an OAuth 2.0 custodian integration that provides direct access to Charles Schwab advisor accounts. This integration syncs investment accounts, positions, balances, and cost basis data from Schwab’s official Financial Advisor API.
Overview
Section titled “Overview”| Attribute | Value |
|---|---|
| Integration Type | Custodian (API-based) |
| Authentication | OAuth 2.0 with OpenID Connect |
| Data Flow | Schwab → RightCapital (inbound only) |
| Scope | readonly |
| Developer | Yan Hu |
| Cron Owner | yan.hu |
Data Synced
Section titled “Data Synced”| Entity | Description |
|---|---|
| Master Accounts | Financial Advisor master accounts |
| Accounts | Individual investment accounts under master accounts |
| Positions | Current holdings with symbol, quantity, price, market value |
| Balances | Total account balance including cash |
| Cost Basis | Unrealized gain/loss position data |
Authentication
Section titled “Authentication”OAuth 2.0 Flow
Section titled “OAuth 2.0 Flow”The integration uses OAuth 2.0 Authorization Code flow with PKCE and HTTP Basic Auth for token exchange.
Token Management
Section titled “Token Management”The integration uses ThreadSafeOAuthTokenManager for handling token refresh race conditions:
- Token Refresh Before Expiry: Tokens are refreshed 10 seconds before expiration
- Redis Locking: Prevents multiple concurrent jobs from refreshing simultaneously
- 5-Minute Cache: Refreshed tokens cached in Redis for reuse
- Transaction Safety: Stashes credentials for recovery if database transaction rolls back
Rate Limits
Section titled “Rate Limits”| Endpoint | Rate Limit |
|---|---|
| Accounts | 120 req/min |
| Positions | 120 req/min |
| Balances | 120 req/min |
| Cost Basis | 120 req/min |
| Transactions | 60 req/min |
Account Type Mapping
Section titled “Account Type Mapping”| Schwab Type | RightCapital Subtype |
|---|---|
HSA Custodial, HSA Master, HSBA |
HSA |
403(b)7, I401(k), Rtmt Plan Srvc |
401k |
Contrib, Rollover, Custodial Ira, Inh IRA |
Traditional IRA |
Roth Contrib, Roth Conversion |
Roth IRA |
Simple Ira, Simple Ira Plan |
SIMPLE IRA |
Sep, Sarsep |
SEP IRA |
Educ Savings |
529 |
Liv Trust, Fid Trust, Test Trust |
Trust |
Schwab Chartble |
Donor |
Pen Trust, PEN ADM |
Pension (Taxable) |
| (Most others) | Taxable |
The full mapping includes 70+ account types.
API Endpoints
Section titled “API Endpoints”| Endpoint | Purpose |
|---|---|
master-accounts |
List FA master accounts |
accounts |
List accounts under a master account |
account-owners/list |
Get account details for specific references |
positions/detail |
Get position data for an account |
balances/detail |
Get balance for an account |
cost-basis/ugl-positions |
Get unrealized gain/loss (cost basis) |
Code Locations
Section titled “Code Locations”| Component | Path |
|---|---|
| Connector | retail-api/app/Integrations/SchwabApi/Connector.php |
| Integrator | retail-api/app/Integrations/SchwabApi/Integrator.php |
| Controller | retail-api/app/Integrations/SchwabApi/Controller.php |
| Config | retail-api/app/Integrations/SchwabApi/Config.php |
| Sync | retail-api/app/Integrations/SchwabApi/Sync.php |
| Models | retail-api/app/Integrations/SchwabApi/Models/ |
| Token Manager | retail-api/app/Integrations/Support/LegacyApiBased/Connectors/ThreadSafeOAuthTokenManager.php |
Common Issues
Section titled “Common Issues”Token Refresh Race Condition
Section titled “Token Refresh Race Condition”Symptom: Multiple concurrent sync jobs fail with authentication errors.
Solution: The integration uses ThreadSafeOAuthTokenManager with Redis locking.
Terms & Conditions Not Accepted
Section titled “Terms & Conditions Not Accepted”Symptom: Error about not accepting Schwab Cost Basis Terms & Conditions.
Solution: Advisor must log into Schwab Advisor Center and accept the Cost Basis Terms & Conditions.
Account Not Found (SEC-0100/SEC-0101)
Section titled “Account Not Found (SEC-0100/SEC-0101)”Symptom: Some accounts fail to sync with 401 errors.
Solution: Account was closed, transferred, or authorization was revoked. The advisor may need to reconnect.
Related
Section titled “Related”- Orion - Similar investment account integration