Connect and manage your firm's Alpaca custodian

Your firm connects its Alpaca Broker API keys to its Tilt organization. One connection covers every client account the firm holds under its Alpaca correspondent code. Tilt reads those accounts through it and sends approved trades through it.

​

Who can do what

Changes need the owner’s own Tilt sign-in. Tilt Agent can read the status and open the card, and it never changes the connection itself. When the card appears in Claude, ChatGPT, or another connected app, it shows the status with Open Tilt to make changes, or Open Tilt to connect before the first connection. Other members see the status read-only, with the note Only firm owners can connect or change the custodian.

​

Open the custodian card

In your firm’s organization, ask Tilt Agent for it, for example “Open the custodian card so I can replace our keys.” You can also ask Tilt Agent for the Connect brokerage card and choose Alpaca Broker API, which lists your firm’s status.

​

Get the keys from Brokerdash

Create the API keys in Alpaca’s Brokerdash before you connect.

1. Sign in to the Brokerdash of the environment you want to connect: sandbox or live. Keys work only in the environment they were created in.
2. Create API credentials that use a client secret.
3. Choose custom access: read and write for Accounts and Trading, and read only for Data and Reporting. For sandbox keys, also give Journaling read and write, which Deposit paper funds uses to move practice cash into client accounts. Give no access to the other areas. Tilt can check only what the keys read before it saves them, so keys without write access still connect but fail later, when Tilt sends a trade or deposits paper funds.
4. Copy the client ID and the client secret. Brokerdash shows the secret once.

Have two more values ready: your firm’s correspondent code, and the ID of the firm’s sweep account, the Alpaca account that holds the firm’s cash. Note the expiry date you set on the keys.

​

1. Connect the firm

1. Choose Sandbox or Live under Environment.
2. Enter the Correspondent code, Client ID, Client secret, and Firm sweep account ID.
3. Enter Keys expire on if the keys have an expiry date. Enabled account types is optional.
4. Select Connect firm.

Tilt checks the keys before it saves anything. With the keys, it reads the firm’s account list, the sweep account, and the sweep account’s balances. It refuses keys that can’t read trading accounts, keys of a firm that is already connected to Tilt in the same environment, and keys that reach client accounts another Tilt connection holds. Each environment of a custodian firm connects to one Tilt organization only. When Tilt refuses the keys, the card shows the reason. Enter keys only in the card. Don’t paste them into a chat message. To connect a second firm, or the same firm’s other environment, select Connect another. Connecting the same firm in the same environment again is refused; replace its keys instead.

​

2. Read the connection

Each connection is titled with its correspondent code and environment, with a Connected or Needs attention badge. Tilt doesn’t send a reminder before the keys expire. Set your own reminder to replace them ahead of the date. When a connection needs attention, the card shows This connection stopped working. with the custodian’s message. An owner fixes it with Replace keys in that warning.

​

3. Replace the keys

Replace the keys before they expire, or when the connection needs attention.

1. Create new keys in Brokerdash, in the same environment as the connection.
2. Select Replace keys.
3. Enter the New client ID and New client secret.
4. Enter New keys expire on. Leaving it blank clears the current expiry date.
5. Select Replace keys.

Tilt checks the new keys the same way it checks a new connection, and keeps the current keys if the check fails. Once Tilt accepts the new keys, revoke the old ones in Brokerdash, since Tilt can’t revoke keys at Alpaca. A connection’s environment never changes; to move from sandbox to live, connect the live environment with Connect another.

​

4. Sync and review client accounts

Sync now reads the firm’s client accounts from Alpaca. When it finishes, the card says how many client accounts synced, or that the sync was incomplete or failed. Only firm owners can start a sync. Show client accounts lists each client account with its Client column, Linked or Not linked, and a Custodian restriction column that shows why Alpaca limits trading in the account, or None. Every member who can see the connection can open the list. You can also ask Tilt Agent which client accounts a connection holds.

​

5. Disconnect

Select Disconnect to see what disconnecting would do, with your firm’s numbers, before anything changes. Disconnecting:

• takes every client account out of its portfolio groups and closes its holdings in Tilt. Reconnecting later creates new client accounts, so their links to clients don’t come back.
• leaves approved trades that weren’t sent yet approved, but they can’t be sent.
• marks orders that never reached Alpaca as failed. Orders Alpaca already has are left as they are.
• deletes the keys Tilt stored. Tilt can’t revoke keys at Alpaca, so revoke them in Brokerdash too.

To go ahead, type the connection’s correspondent code and select Disconnect. Keep connection closes the warning and changes nothing.

​

Signed out of this firm

If the card says Signed out of this firm, your firm signed you out after a period of inactivity. Sign in to the firm again, then reopen the card. Tilt keeps a record of each connect, key replacement, and disconnect, without the keys. See History coverage for what Tilt records.