Skip to content

Use your X API key

Without a key, X (Twitter) accounts are agent tier: your agent fetches them in its browser. With the household’s own X API key, the Homestead server fetches them itself through the X API v2, which X charges for per use. A monthly budget stops Homestead before it spends more than you allow.

Only the owner can change this.

How the budget guard works

Section titled “How the budget guard works”
  • Before every call to X, Homestead estimates its cost from the rates in the platform registry and adds it to what it has spent this month.
  • If that would go over your monthly budget, the call is skipped. The account shows “Monthly X budget reached. Fetching resumes next month.”
  • Spending resets each month.
  • The default budget is 5 USD a month. You can set 0 to 1000.

The rates live in platforms/platforms.yaml under the x platform: costPerPostReadUsd: 0.005 and costPerUserReadUsd: 0.010. The registry marks them as needing a check against X’s current pricing, so treat them as estimates.

Add the key

Section titled “Add the key”

You need an X API bearer token (app-only auth) from X’s developer site.

On the Sources screen

Section titled “On the Sources screen”
Available on main

Settings → Sources will have a secret field for the key, a Remove button, the monthly budget and the spend this month.

With the API, for now

Section titled “With the API, for now”

Until the screen lands, set the key through the API. You’ll sign in as the owner with a device token, which is easier with curl than a browser cookie.

  1. Sign in as the owner and copy the deviceToken from the reply (it starts with hsd_).

    Terminal window
    curl -X POST http://localhost:8080/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"mali","password":"your-password","client":"device","deviceName":"curl"}'

  2. Save the key and the budget.

    Terminal window
    curl -X PATCH http://localhost:8080/api/v1/settings/sources -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN" -H "Content-Type: application/json" -d '{"xApiKey":"YOUR_X_BEARER_TOKEN","xMonthlyBudgetUsd":5}'

  3. Check the result. The key itself is never returned; you’ll see "xApiKeySet": true, the budget and xSpentUsdThisMonth.

    Terminal window
    curl http://localhost:8080/api/v1/settings/sources -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN"

  4. Sign the device token out when you’re done.

    Terminal window
    curl -X POST http://localhost:8080/api/v1/auth/logout -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN"

Once the key is set, X accounts move to the server tier. The server looks up each user, then fetches their posts with replies and retweets left out.

Change the budget or remove the key

Section titled “Change the budget or remove the key”

Send only the field you want to change. To change the budget:

{ "xMonthlyBudgetUsd": 10 }

To remove the key, send null:

{ "xApiKey": null }

When the key is removed, all X accounts move back to the agent tier.

How the key is stored

Section titled “How the key is stored”

The key is encrypted with AES-256-GCM using the instance’s secret key (/data/secret.key). It is never returned by the API. A backup includes the secret key, so a restored Homestead can still read it; a restore from an archive without the secret key means entering the key again.