Introduction
Our High-Yield Cash API1 is intended to provide partners around the world with a top-of-funnel growth mechanism that enables their customers to earn APR/APY on their USD balances. This resource will cover the essentials of how to get started, as well as end-game mechanics for those wanting to build a premier cash product experience. For an overview of the program and important disclosures, please read our announcement here.
Data Model
First, there are key concepts and relationships that need to be defined to provide context to the API specs and mechanics shown later in this guide.
Accounts have a many-to-one relationship with APR Tiers:
- An account can be associated with only one APR Tier at a time, per currency
- Many accounts can be associated with the same APR Tier
- Any updates to an APR Tier will apply to all accounts associated with it
An account has a new object introduced (cash_interest). And within the cash_interest object is the USD object, which contains two new properties within it:
An APR Tier represents the interest rate an account earns and the fee its partner earns when assigned to it. The core objects are as follows:
The Essentials
Account Eligibility
For accounts created starting August 21, 2024, where the end-customer has signed revision 22.2024.08 or newer of the Customer Agreement, they are eligible to participate upon delivering the program Terms & Conditions.
For accounts created before August 21, 2024, where the end-customer has signed revision 21.2023.06 or older of the Customer Agreement, those accounts will need to digitally sign the latest version in order to be eligible to participate in the program, as well as be delivered the program Terms & Conditions.
Both user journeys require specific front-end language and hyperlinks that our Integration Team will help guide you through during onboarding.
Assign an Account to an APR Tier
After an account is eligible, the next step is to assign the account to its first APR Tier to create the association between the two. During the onboarding process, we’ll have a discussion around the goals of your cash product. Upon conclusion, we will create the APR Tier(s) for you server-side that meet(s) your needs, to help you hit the ground running. In a future release, we intend to expose create, update, and delete UX via API to unlock self-service functionality.
Assignments are facilitated via PATCH through the existing Update an Account endpoint that you are already using for day-to-day operations. For this example, you would PATCH the hypothetical “gold” APR Tier to the account in the path parameter, which for the purposes of this article is configured to 4.25% APR for the customer (account_rate_bps) and a partner take rate (correspondent_fee_bps) of 0.25% APR.
Front-end Considerations: account_rate_bps of the APR Tier that the account is associated with can be converted to a percentage, and displayed dynamically on your front-end for each customer account.
Timing Considerations: If the assignment request is successful before 12:00 pm Eastern Time (ET), then settled cash in the account will be swept into the program same-day and also begin accruing interest same-day.
Request:
PATCH v1/accounts/{account_id}Sample request body:
{
"cash_interest": {
"USD": {
"apr_tier_name": "gold"
}
}Sample response body:
{
"cash_interest": {
"USD": {
"apr_tier_name": "gold",
"status": "PENDING_CHANGE"
}
}
... plus all the other account properties
}Retrieve EOD Cash Balances and Accrued Interest
Daily at end-of-day (EOD), the EOD Cash Interest Details endpoint provides an account-level breakdown of critical data needed to directly power your front-end customer experience and set your Operations/Support team up for success:
- Daily snapshot of an account’s High-Yield Cash balance, the assigned APR Tier, and the accrued interest earned that day.
- Query parameters enable you to self-serve customer inquiries about cash balances and accrued interest on or across specific dates.
Front-end Considerations: Daily account_accrued_interest can be stored, summed, and presented on your front-end to show intra-month accrued interest to your respective customers.
Timing Considerations: The endpoint is typically updated at 8:00 pm Eastern Time (ET) and reflects that day’s ending state.
Sample request for the latest available EOD report across all accounts:
GET v1/reporting/eod/cash_interestSample response body:
{
“date”: “2024-06-11”,
“account_id”: “382dd20d-d627-4d9f-9c93-7e24cd340546”,
"apr_tier_name": "gold",
"apr_tier_id": "13d149c8-d620-43e0-978b-88af8abb2ef1",
"currency": "USD",
“cash_balance”: “10000.00”,
“account_rate_bps”: 425,
“account_accrued_interest”: “1.1806”,
“corresopndent_rate_bps”: 25,
“correspondent_fee” : “0.0694”
},
{
“date”: “2024-06-11”,
“account_id”: “744d2e94-1a3d-4ef4-bd60-ec8e078a453a”,
"apr_tier_name": "gold_promo",
"apr_tier_id": "14d149c8-d620-43e0-978b-88af8abb2ef2",
"currency": "USD",
“cash_balance”: “10000.00”,
“account_rate_bps”: 450,
“account_accrued_interest”: “1.2500”,
“corresopndent_rate_bps”: 0,
“correspondent_fee” : “0.00”
}Sample request for a specific account across multiple dates:
GET v1/reporting/eod/cash_interest?account_id=382dd20d-d627-4d9f-9c93-7e24cd340546&start=2024-06-13&end=2024-06-11&page_size=1000Sample response body:
{
“date”: “2024-06-13”,
“account_id”: “382dd20d-d627-4d9f-9c93-7e24cd340546”,
"apr_tier_name": "gold",
"apr_tier_id": "13d149c8-d620-43e0-978b-88af8abb2ef1",
"currency": "USD",
“cash_balance”: “10000.00”,
“account_rate_bps”: 425,
“account_accrued_interest”: “1.1806”,
“corresopndent_rate_bps”: 25,
“correspondent_fee” : “0.0694”
},
{
“date”: “2024-06-12”,
“account_id”: “382dd20d-d627-4d9f-9c93-7e24cd340546”,
"apr_tier_name": "gold",
"apr_tier_id": "13d149c8-d620-43e0-978b-88af8abb2ef1",
"currency": "USD",
“cash_balance”: “10000.00”,
“account_rate_bps”: 425,
“account_accrued_interest”: “1.1806”,
“corresopndent_rate_bps”: 25,
“correspondent_fee” : “0.0694”
},
{
“date”: “2024-06-11”,
“account_id”: “382dd20d-d627-4d9f-9c93-7e24cd340546”,
"apr_tier_name": "gold",
"apr_tier_id": "13d149c8-d620-43e0-978b-88af8abb2ef1",
"currency": "USD",
“cash_balance”: “10000.00”,
“account_rate_bps”: 425,
“account_accrued_interest”: “1.1806”,
“corresopndent_rate_bps”: 25,
“correspondent_fee” : “0.0694”
}Retrieve Month-End Realized Interest
Monthly on the last business day of the month (non-bank holiday or weekend), the respective account_accured_interest for that month is rounded to the 2nd decimal place and credited to your customer accounts visible at the Account Activities endpoint. The qty figure, representing the number of dollars of realized interest paid, will also be included in that day’s cash_balance figure in the above EOD Cash Interest Details endpoint response. While by default the qty remains within the program to compound into yield, it is immediately usable as buying power for trading activity or for journal activities once credited.
Front-end Considerations: qty can not only be shown in an activities feed on your front-end, but can also be stored, summed, and displayed to represent lifetime interest earnings for each customer account.
Timing Considerations: The endpoint is typically updated at 6:00 pm Eastern Time (ET) on the last business day of the month.
Request:
GET v1/accounts/activities/INTSample response body:
{
"id": "382dd20d-d627-4d9f-9c93-7e24cd340546",
"qty": 34.42,
"price": null,
"status": "executed",
"symbol": "SWEEPFDIC",
"entry_type": "INT",
"net_amount": 0,
"description": "June 2024 Sweep",
"settle_date": "2024-06-28",
"system_date": "2024-06-28",
"entry_sub_type": "SWP",
"per_share_amount": null
}List APR Tiers
To view your current APR Tier(s) and their existing configuration(s), you can state sync daily against the List APR Tiers endpoint.
Request:
GET v1/cash_interest/apr_tiersSample response body:
{
"apr_tiers": [
{
"id": "382dd20d-d627-4d9f-9c93-7e24cd340546",
"currency": "USD",
"name": "gold",
"is_default": true,
"correspondent_rate_bps": 25,
"account_rate_bps": 425,
"created_at": "2024-06-11T20:06:32.207729Z",
"updated_at": "2024-06-11T20:06:32.207729Z",
"details": {
"total_accounts": 7542,
"total_balance": "50450485.76",
"as_of": "2024-06-28"
}
}
]
}The End-Game
Reassign the Account to a different APR Tier
Most use-cases will utilize more than one APR Tier to carry out different growth and customer segmentation strategies. One example is having a two APR Tier setup, where one is the default customer rate and the other is a higher promotional rate to power a referral program where both parties get a “boosted rate” for a defined amount of time upon a successful referral. Another setup more common to neobanks is offering multiple APR Tiers based on custom qualifying activity such as average monthly balances, setting up direct deposits, etc. With any of these multi-APR Tier strategies comes the need to reassign an account to a different APR Tier, which is supported up to a daily frequency by API.
Reassignment requests are facilitated the exact same way as an initial Assignment by PATCHing a new APR Tier to an account through the existing Update an Account endpoint.
Timing Considerations: If the reassignment request is successful before 12:00 pm Eastern Time (ET), then the account will begin accruing interest same-day at the new APR Tier’s account_rate_bps.
Request:
PATCH v1/accounts/{account_id}Sample request body:
{
"cash_interest": {
"USD": {
"apr_tier_name": "silver"
}
}Sample response body:
{
"cash_interest": {
"USD": {
"apr_tier_name": "silver",
"status": "PENDING_CHANGE"
}
}
... plus all the other account properties
}Track the Status of the Account
As the number of your enrolled accounts grows, regularly retrieving and/or querying historical account status logs will become an important practice for state management and debugging. The three states that status can have are defined as follows:
Timing Considerations: Between 12:15pm - 2:00pm ET is when cash_interest.status can cycle for the day from PENDING_CHANGE to ACTIVE or INACTIVE.
The first way of retrieving program status is through two existing endpoints you are likely to already be integrated with: Get All Accounts or Get an Account by ID. Both will have the below nested objects in the response:
"cash_interest": {
"USD": {
"apr_tier_name": "gold",
"status": "ACTIVE"
}
}Another way of retrieving program status is through the existing Account Status SSE that can be used as a streaming mechanism or be treated as a closed connection to query for ad-hoc debugging/investigation.
Example:
- On 2024-05-10 at 12:00 UTC, you submit a PATCH request Assigning the APR tier for account_id = 382dd20d-d627-4d9f-9c93-7e24cd340546. Cash Interest program status changes to PENDING_CHANGE.
- On 2024-05-10 at 17:00 UTC, Alpaca’s EOD process completes and the status for the account changes to ACTIVE.
- On 2024-06-11 at 13:00 UTC, the customer gets flagged as a Pattern Day Trader (PDT) or requests to be unenrolled from the program. Status changes to PENDING_CHANGE.
- On 2024-06-11 at 17:00 UTC, Alpaca’s EOD process completes and the status for the account changes to INACTIVE.
Request:
GET v1/events/accounts/status?id=382dd20d-d627-4d9f-9c93-7e24cd340546&since=2024-05-10&until=2024-06-11Response with comments added as hints:
[
# Change 4:
{
"cash_interest": {
"USD": {
"status_from": "PENDING_CHANGE",
"status_to": "INACTIVE"
}
},
"account_id": "382dd20d-d627-4d9f-9c93-7e24cd340546",
"at": "2024-06-11T19:00:00.000000Z",
"event_ulid": "01J2VQMVJRMXQRPNS3831XFE1Y"
},
# Change 3:
{
"cash_interest": {
"USD": {
"status_from": "ACTIVE",
"status_to": "PENDING_CHANGE",
}
},
"account_id": "382dd20d-d627-4d9f-9c93-7e24cd340546",
"at": "2024-06-11T13:00:00.000000Z",
"event_ulid": "11J2VQMVJRMXQRPNS3831XFE1Y"
},
# Change 2:
{
"cash_interest": {
"USD": {
"status_from": "PENDING_CHANGE",
"status_to": "ACTIVE",
}
},
"account_id": "382dd20d-d627-4d9f-9c93-7e24cd340546",
"at": "2024-05-10T19:00:00.000000Z",
"event_ulid": "21J2VQMVJRMXQRPNS3831XFE1Y"
},
# Change 1:
{
"cash_interest_from": {
"USD": {
"status_from": "INACTIVE",
"status_to": "PENDING_CHANGE",
}
},
"account_id": "382dd20d-d627-4d9f-9c93-7e24cd340546",
"at": "2024-05-10T12:00:00.000000Z",
"event_ulid": "31J2VQMVJRMXQRPNS3831XFE1Y"
}
]Unenroll an Account
To unenroll an account, PATCH its cash_interest.status to INACTIVE. When an account enters an INACTIVE state, the association between it and its APR Tier will be removed. To re-enroll the account in the future, simply submit an Assignment request.
Timing Considerations: A successful unenroll request before 12:00 pm ET will result in the account’s cash_balance being swept out of the program same-day. The EOD Cash Interest Details response for that day will reflect a cash_balance = 0.00 and account_interest_accrued = 0.00. If the unenroll request is received after the daily 12:00pm ET cutoff, then it will be queued for processing the next business day.
Request:
PATCH v1/accounts/{account_id}Sample request body:
{
“cash_interest”: {
"USD": {
"status" : "INACTIVE"
}
}
Response:
{
"cash_interest": {
"USD": {
"apr_tier_name": "silver",
"status": "PENDING_CHANGE"
}
}
... plus all the other account properties
}Next Steps
Thank you for following along for the journey and we look forward to supporting your growth strategy with our High-Yield Cash API.
- For prospective partners, please reach out to Alpaca’s Sales team at [email protected].
- For existing partners, please reach out to your Customer Success Manager (CSM) or email the Success team at [email protected].
1. ‘High-Yield Cash’ or ‘High-Yield Cash API’ is a technology product offered by AlpacaDB, Inc. (“Alpaca”) which allows users to, among other things, access securities brokerage services provided by Alpaca Securities LLC ("Alpaca Securities"), including but not limited to the Alpaca Securities LLC FDIC Bank Sweep Program (the “FDIC Bank Sweep” or “Program”). Alpaca Securities is a member of FINRA/SIPC, and is a wholly-owned subsidiary of AlpacaDB, Inc. Please see alpaca.markets/disclosures for further information and important disclosures.
Alpaca Securities offers a cash management program pursuant to the FDIC Bank Sweep. Customer funds are treated differently and are subject to separate regulatory regimes depending on whether customer funds are held in their brokerage account or within the FDIC Bank Sweep. Specifically, Alpaca Securities is a member of the Securities Investor Protection Corporation (SIPC), which protects securities customers of its members up to $500,000 (including $250,000 for claims for cash). The Federal Deposit Insurance Corporation (FDIC) insures up to $250,000 per deposit against the failure of an FDIC member bank. Customer funds held in brokerage accounts are SIPC insured, but are not eligible for FDIC insurance coverage. Funds maintained in the FDIC Bank Sweep are intended to be eligible for pass-through FDIC insurance coverage, but are not subject to SIPC coverage. FDIC insurance coverage does not protect against the failure of Alpaca, Alpaca Securities, or any of its or their affiliates and/or malfeasance by any Alpaca or Alpaca Securities employee. Program banks that participate in the FDIC Bank Sweep are not members of SIPC and therefore funds held in the Program are not SIPC protected. Please see alpaca.markets/disclosures for important additional disclosures regarding Alpaca Securities brokerage offering as well as FDIC Bank Sweep terms and conditions.
Please note that the content of this piece article is for general information only and is believed to be accurate as of the posting date but may be subject to change. Alpaca does not provide investment, tax, or legal advice. Please consult your own independent advisor as to any investment, tax, or legal statements made herein.
All investments involve risk, and the past performance of a security, or financial product does not guarantee future results or returns. There is no guarantee that any investment strategy will achieve its objectives. Please note that diversification does not ensure a profit, or protect against loss. There is always the potential of losing money when you invest in securities, or other financial products. Investors should consider their investment objectives and risks carefully before investing.
Securities brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.
This is not an offer, solicitation of an offer, or advice to buy or sell securities or open a brokerage account in any jurisdiction where Alpaca Securities are not registered or licensed, as applicable.