Skip to content

Let an AI trade for you

An AI picks what to buy. It can act only while you allow it, and every yes and every no is signed on your computer.

An AI looks at Apple and the S&P 500 and picks one to buy. It tries, and EKKA stops the order, because you have not given it permission. You give it permission to trade, for as long as you choose, and the same order goes through to your Alpaca paper account. You take the permission back, and the next order is stopped.
Trust Every step is written down and signed on your computer. At the end, your computer checks that record without asking EKKA.
Security The AI can do only what you allowed, and only for as long as you allowed it.
Privacy Your broker keys stay on your computer and go only to Alpaca. EKKA and the AI never see them. To decide yes or no, EKKA's control plane is sent the message to the AI and the order. The AI gate carries the message to the model, a third party, not EKKA. Your balance and your other orders stay on your computer. Want your own model instead? Add its API to your catalog the same way this kit added Alpaca (connect your own API). Then the message goes to your model, not a third party's.

Paper money only: Alpaca's practice account, with no bank and no real money. The buying rule is an example, not advice.

The kit is a folder in github.com/ekka-labs/kits, version financial-api-agent/2.0.0. Read open.sh before you run it.

What you need

  • A Mac, a Linux box, or a container, with python3.
  • An Alpaca account with paper trading turned on. Paper trading needs no bank and no funding.
  • Your paper API keys. You paste the key id and the secret once, at prompts that hide them.

Your Alpaca paper keys

  1. Sign in at app.alpaca.markets.
  2. Open your profile, then Manage Accounts, then Paper Accounts, then API Keys.
  3. Click Regenerate. The secret is shown once. Keep both until the kit asks for them.

Your keys are yours. Never share them, not even with a colleague running this kit. Anyone holding the pair can place paper orders in your account. If a key ever reaches somebody else, click Regenerate, which retires the old pair at once.

Install and start

The installer checks that the binary was signed by EKKA's release workflow before it installs it, so the machine needs cosign first:

# macOS
brew install cosign
# Linux, x86_64 (on arm64, use cosign-linux-arm64)
sudo curl -fsSLo /usr/local/bin/cosign https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
sudo chmod +x /usr/local/bin/cosign

The machine must reach Sigstore

cosign checks the signature against Sigstore's public log, so the machine needs to reach rekor.sigstore.dev and tuf-repo-cdn.sigstore.dev. Without cosign, or without that access, the installer stops and says which one it is.

curl -fsSL https://get.ekka.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
ekka login --email [email protected]
ekka org create <a short name for your organization, letters and dashes>
ekka enclave create --name "trading agent"
ekka enclave start <the id it printed>

Leave that window running: it is the Enclave, the part of EKKA that runs on your computer. In a second window:

git clone https://github.com/ekka-labs/kits
cd kits/financial-api-agent
./open.sh

The kit says what it will set up and asks first. It shows each command before it runs it, runs it in front of you, and says what happened in plain words. q stops at any point.

If your organization runs more than one Enclave, add ENCLAVE=<the 8-character id> in front of ./open.sh so the kit knows which one is yours.

What the kit changes

It says this on screen and asks before each change. Each one is a file or a row you can read:

Change Check it yourself
Your Alpaca paper keys are stored, encrypted, on your computer ekka secret list. No command prints them back.
Your organization can reach two Alpaca servers, prices and paper orders, from your computer only catalog/ekka-alpaca-data.json and catalog/ekka-alpaca-paper.json in the kit folder
An agent named trading-agent exists ekka gate grant list --agent trading-agent
Its plans exist as files: read prices, read your paper account, pick what to buy, send an order, cancel it cat trade.*.json in the kit folder
It may read prices, read your paper account, and ask the AI. It may not place an order until you allow that in step 2 ekka gate grant list --agent trading-agent

The four steps

  1. The AI picks what to buy, and tries to buy it. It has no permission to buy, so EKKA stops the order. The kit asks Alpaca directly and shows that no order was placed.
  2. You give permission to trade, for as long as you choose. The same pick goes to EKKA again as the same order, and Alpaca accepts it. The AI is not asked again.
  3. Cancel the order, then take the permission back. The kit reads Alpaca until the order is final, and shows you where to see it in your paper dashboard.
  4. The same order once more. EKKA stops it.

Then the kit checks the signed record on your computer, with no call to EKKA, and sums up what happened under Trust, Security and Privacy.

Good to know

  • Taking the permission back stops new orders. An order already placed stays until you cancel it, which is why step 3 cancels first.
  • The permission sets how long, not which stock or how much. That is on purpose: the kit shows the gate, not a trading strategy.
  • ./open.sh why answers the questions people ask, and how to check each answer yourself. ./open.sh commands lists every command the kit ran.

The ideas the kit uses are explained here: how governance works, what leaves your machine, grant conditions and the signed record.

Clean up

When you are done, take back what the kit set up. Each step is one command, run as you, in the kit folder.

  1. Take back every permission the agent holds. List them, then revoke each one by its id:

    ekka gate grant list --agent trading-agent
ekka gate grant revoke <the grant id>

    The kit already took back the permission to trade in step 3. What is left is reading prices, reading your paper account and asking the AI.

  2. Remove your Alpaca keys from this computer. Your organization's name is the first part of each connection, as ekka api list shows it. --yes confirms the removal:

    ekka api disconnect <your organization>/alpaca-paper --yes
ekka api disconnect <your organization>/alpaca-data --yes

    Then check that the keys are gone. This lists the secrets kept on this computer:

    ekka secret list

    No line should end in ALPACA_PAPER or ALPACA_DATA. If one does, remove it by the name shown:

    ekka secret remove <the name shown>

  3. Retire the keys at Alpaca too, if you will not use them again: in app.alpaca.markets, Paper Accounts, API Keys, Regenerate.

  4. What stays, by choice. The agent trading-agent and its saved plans stay in your organization, with no permissions left after step 1. Your receipts stay too: they are the record of what happened. The prices and answers the agent read stay in this computer's EKKA folder until you remove it.

  5. Remove the kit's folder when you no longer want its plans as files. If you ran it in Docker, docker stop kitbox then docker rm kitbox. Removing the folder or the container does not take back permissions, so do steps 1 and 2 first.