Agent API

Public endpoints

Agent resources (Bearer token)

Discovery

Authentication

• Create a personal API token on `/profile`.
• Use `Authorization: Bearer <token>` on every Agent API request.
• Treat the token like a password: store it only in your AI agent’s secure config; rotate or revoke from profile if exposed.

Quick connect flow

1. 1

   Read integration metadata (optional)

   Read `/.well-known/agent-integration.json` for canonical URLs.

   • You know the signal and heartbeat paths
2. 2

   Generate a token on profile

   Open `/profile`, create a personal API token, and copy it once into your AI agent configuration.

3. 3

   Call the signal endpoint

   Use `GET /api/v1/agent/signal` with the Bearer token to retrieve the daily DCA weight for the subscriber.

Example: curl with a personal API token

curl -sS \
  -H "Authorization: Bearer YOUR_PERSONAL_API_TOKEN" \
  "https://www.stackingsats.org/api/v1/agent/signal"

Replace YOUR_PERSONAL_API_TOKEN with the value from your profile.

Official SDKs

• TypeScript: sdk/typescript — StackingSatsAgentClient with fetchDailySignal and heartbeat.
• Python: sdk/python — StackingSatsAgentClient with fetch_daily_signal and heartbeat.

End-to-end builder walkthrough: /docs/resources/agent-builder-guide.

Machine-readable contract:

• OpenAPI: /openapi/agent/v1.json
• Error schema: /schemas/agent-api-error.json
• Signal schema: /schemas/agent-signal-response.json

Source contract in the repository: docs/AGENT_API_OPENAPI.yaml.

Responses and error codes

Successful signal responses return 200 with a JSON body (see SDKs). Error responses use a stable JSON envelope, and the full machine-readable contract is published at /openapi/agent/v1.json.

Common categories:

• Request/authentication: INVALID_REQUEST, INVALID_DATE, UNAUTHORIZED, FORBIDDEN
• Subscriber/data state: SIGNAL_NOT_FOUND, SUBSCRIPTION_PERIOD_INVALID, DCA_DATA_UNAVAILABLE
• Platform/infrastructure: API_TOKENS_MISCONFIGURED, INTERNAL_ERROR

Heartbeat returns the same envelope on errors; success is 200 with { "ok": true, "server_time": "..." }.

Common errors

All API errors use a stable envelope:

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "request_id": "uuid"
}

Troubleshooting

401 Unauthorized on signal or heartbeat

• Token missing, mistyped, or revoked; regenerate in profile.

403 Forbidden

• Scope mismatch; ensure the token was issued for Agent API use as documented.

404 SIGNAL_NOT_FOUND

• No resolved signal for the subscriber and date; confirm the plan window and requested date (HST).

409 SUBSCRIPTION_PERIOD_INVALID

• Update plan dates on /profile so the subscription aligns with available model data.

503 DCA_DATA_UNAVAILABLE

• No rows in bitcoin_dca for this environment, or plan dates outside a valid period.

503 API_TOKENS_MISCONFIGURED

• Deployment or infrastructure issue; operators should verify environment variables and docs/AGENT_API_RUNBOOK.md in the repository (not an end-user configuration fix).