自建 API key 说明

English

For API queries of the MacroAlpha content library we recommend Agent J: install the MacroAlpha Library skill from the Agent J Plaza and let your own agent call it, with no keys to manage. Paid members can also create their own API key and call the API directly, as described below.

Who can create a key

Any account with an active paid membership (Wuchang or above). If the membership lapses, existing keys are paused (403) and resume automatically when it is renewed.

What you can query

Published episodes of the MacroAlpha Chinese channel: list and filter, episode details, semantic search, and a "have you covered this topic?" check. Free episodes include the full transcript, and search results usually include snippets; members-only episodes return public metadata (title, date, links) only, without transcript or snippets. Unpublished or scheduled content is never returned.

Prices (charged to your account credits; 1 credit = $0.001)

• GET /episodes and GET /episodes/{id}: 10 credits ($0.01) per call.
• POST /search and POST /coverage: 20 credits ($0.02) per call.
• GET /usage: free.
• Only successful calls are charged. If your balance is below the price of the call, you get 402 and nothing is charged.

Limits

Up to 5 active keys per account; at most 3 creations and 3 revocations per 24 hours. Each key: 60 requests per minute and 5,000 per day, of which search and coverage 20 per minute; usage 60 per hour. Over the limit you get 429 with a Retry-After header.

Step 1: sign in for a short-lived access token

curl -s https://app.macroalpha.io/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"<your password>"}'

If you have always signed in with Apple or Google and never set a password, first use "Forgot password" on the sign-in page with your account email (for Hide My Email, the relay address) to set one. The accessToken is used here to create, list and revoke keys and is valid for 15 minutes; it is equivalent to your sign-in credentials, so keep it private.

Step 2: create a data key

curl -s https://app.macroalpha.io/api/account/api-keys \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my data key","scopes":["data"]}'

scopes must be ["data"]; without it the key has no data access (calls return 403) and the attempt still counts toward the daily creation limit.

The key field is your full API key and is shown only once. Store it in a password manager or environment variable right away; a lost key cannot be recovered, only revoked and replaced. apiKey.id identifies the key for revocation.

Sign out when you are done. An account keeps at most 5 sign-in sessions, so repeated sign-ins without signing out can sign your phone app or browser out:

curl -s -X POST https://app.macroalpha.io/api/auth/logout \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Step 3: call the API with your key

Base URL https://app.macroalpha.io/api/v1/data; send Authorization: Bearer <YOUR_API_KEY> with every request.

curl -s 'https://app.macroalpha.io/api/v1/data/episodes?pageSize=5' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

curl -s https://app.macroalpha.io/api/v1/data/search \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"query":"Does AI have Buddha-nature?","topK":5}'

On successful calls, the X-Credits-Charged and X-Credits-Balance response headers show the credits charged and your remaining balance; GET /usage lets you check at any time.

List and revoke

curl -s https://app.macroalpha.io/api/account/api-keys \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

curl -s -X DELETE https://app.macroalpha.io/api/account/api-keys/<KEY_ID> \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Revocation takes effect immediately and cannot be undone. Revoke and replace a key at once if you think it has leaked; never put it in public code or screenshots.

Terms

For reference and research only; do not republish or redistribute full texts. For help, use Messages → Contact Support in the app or email founder@macroalpha.io.