Agent builder guide

Build an agent

From API token to daily DCA execution

Walk through token setup, signal retrieval, and optional heartbeat using the public Agent API and official SDK helpers.

Agent API referenceResources overview

Context

The AI agent you run or configure (for example OpenClaw, a custom script, or a hosted service) pulls daily optimized DCA weights from Stacking Sats and executes trades on the user's preferred external exchange or venue. Stacking Sats provides the signal only; your AI agent owns scheduling and order placement.

1. Get your API token

Generate a personal API token from /profile and store it only in your AI agent’s secure configuration.

If your agent supports discovery-first setup, read /.well-known/agent-integration.json first to get the canonical endpoint and contract URLs.

2. Read the daily signal

GET /api/v1/agent/signal with Authorization: Bearer <your_api_token>.

• Optional query: date, include_recommended.
• Handle 404 (SIGNAL_NOT_FOUND) when no signal exists for the subscriber/date; handle 503 (DCA_DATA_UNAVAILABLE) when DCA data is missing for the environment.
• Handle 409 (SUBSCRIPTION_PERIOD_INVALID) by fixing plan dates on /profile.

3. Optional: heartbeat

POST /api/v1/agent/heartbeat with the same Bearer token to refresh “last used” metadata for the token (SDK: heartbeat / heartbeat).

4. Testing checklist

• Bearer token works for signal.
• Signal returns resolved_date and expected weight for a known test subscriber.
• Heartbeat returns 200 with ok and server_time when you call it.
• Plan period errors return 409 (SUBSCRIPTION_PERIOD_INVALID) until /profile dates are valid.

Prerequisites

• Read the Agent API reference for exact request and response shapes.
• Use a sandbox subscriber when possible.

Next Step

Agent API

• Glossary

Related Pages

• Resources overview