Eskyee · mintlify · Mar 23, 2026
diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx
@@ -255,7 +255,7 @@

 <Note>Provisioning requests may be processed asynchronously through the background task queue. The agent is created immediately with a `provisioning` status and transitions to `running` once the backend deployment endpoint confirms the deployment. If deployment fails, the status changes to `error`.</Note>

 <Note>The provisioning endpoint calls `POST /api/deployments` on the backend to deploy the agent container. The request includes a 15-second timeout. When the model is set to `claude-opus-4-6`, the AI provider is automatically set to `anthropic`; otherwise it falls back to the provider specified in the agent configuration (default: `openrouter`). The plan sent to the backend defaults to `label` when no tier is specified.</Note>

 ### Request body

@@ -393,7 +393,7 @@
 | `version` | string | Clone service version |
 | `protocol` | string | Payment protocol used |
 | `clonePrice` | string | Current price to clone an agent |
 | `chainId` | number | Blockchain chain ID for payments |

 ## List provisioned agents

@@ -849,7 +849,7 @@

 ## Agent verification

 Agents can be verified using multiple verification types: `eas` (Ethereum Attestation Service), `coinbase`, `ens`, or `webauthn`.

 ### Get verification status

@@ -887,7 +887,7 @@
 | `walletAddress` | string | No | Address of the verifying wallet (web API) |
 | `signature` | string | No | Wallet signature for verification (web API) |

 <Note>The web API always sets `verified: true` on success. The backend accepts an additional `verified` boolean, `verifierAddress`, and `metadata` object directly.</Note>

 #### Response

@@ -931,7 +931,7 @@

 <Warning>This endpoint is subject to the general rate limit of 120 requests per minute per IP.</Warning>

 The request is proxied to the backend provisioning service. When `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET` are configured, the backend creates a real Mux live stream via the Mux API with public playback policy. When Mux credentials are not configured, placeholder streaming credentials are returned instead.

 ### Request body

@@ -966,13 +966,13 @@
 }
 ```

 <Note>The `/api/provision` proxy returns only `success`, `userId`, `subdomain`, `url`, `streamKey`, and `liveStreamId`. The full response shape from the backend provisioning service is shown below.</Note>

 ### Full backend response

 When calling the backend provisioning service directly, the response includes additional fields.

 <Warning>Channel tokens (`telegramToken`, `discordBotToken`, `whatsappToken`) are no longer included in the provision response. Tokens are write-only secrets — they are stored server-side but never returned to the caller.</Warning>

 ```json
 {
@@ -1079,7 +1079,7 @@

 Each provider includes a fallback model in the container config that is used automatically when the primary model is unavailable or returns an error.

 <Note>`minimax` is available as a fallback in the provider configuration map but is not currently accepted as a value for the `aiProvider` request parameter. Passing `minimax` as `aiProvider` returns a `400` validation error. This provider may be enabled in a future release.</Note>

 ## Channel configuration

@@ -1114,7 +1114,7 @@
 |---------|-------|-------------|
 | `dmPolicy` | `allowlist` or `pairing` | `allowlist` when owner IDs are provided, `pairing` otherwise |
 | `dm.enabled` | `true` | Accept direct messages |
 | `dm.groupEnabled` | `false` | Group DMs are disabled |
 | `historyLimit` | `20` | Number of messages retained in context |
 | `streaming` | `partial` | Enable partial message streaming |
 | `retry.attempts` | `3` | Maximum retry attempts |
@@ -1456,7 +1456,7 @@
 |-------|------|----------|-------------|
 | `action` | string | Yes | `set-credential` |
 | `key` | string | Yes | Credential key (for example, `anthropic`, `telegram`) |
 | `value` | string | No | Credential value. When omitted, the credential is marked as unconfigured. |

 ```json
 {
@@ -1475,6 +1475,255 @@
 | 404 | Session not found |
 | 500 | Internal error |
 
+## Agent MPP wallets
+
+```http
+GET /api/agent/mpp
+POST /api/agent/mpp
+```
+
+Manages agent crypto wallets for the Machine-Payable Protocol (MPP). Agents use these wallets to make and receive on-chain payments autonomously. All requests require session authentication.
+
+### GET actions
+
+Pass the `action` query parameter to select the operation.
+
+#### List wallets
+
+```http
+GET /api/agent/mpp
+```
+
+Returns available endpoints and version information when no action is specified.
+
+#### List all wallets
+
+```http
+GET /api/agent/mpp?action=list-wallets
+```
+
+```json
+{
+  "wallets": [
+    { "agentId": "agent_123", "companyId": "company_456", "address": "0x1234...abcd" }
+  ]
+}
+```
+
+#### Get wallet
+
+```http
+GET /api/agent/mpp?action=get-wallet&agentId=agent_123
+```
+
+Returns the wallet for a specific agent, or `404` if no wallet exists.
+
+```json
+{
+  "agentId": "agent_123",
+  "address": "0x1234...abcd"
+}
+```
+
+#### Get balance
+
+```http
+GET /api/agent/mpp?action=get-balance&agentId=agent_123
+```
+
+Returns the USDC balance for an agent's wallet.
+
+```json
+{
+  "agentId": "agent_123",
+  "balance": "10.50"
+}
+```
+
+### POST actions
+
+Pass the `action` field in the request body.
+
+#### Create wallet
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | string | Yes | `create-wallet` |
+| `agentId` | string | Yes | Agent identifier |
+| `companyId` | string | Yes | Company identifier |
+
+```json
+{
+  "success": true,
+  "agentId": "agent_123",
+  "companyId": "company_456",
+  "address": "0x1234...abcd",
+  "privateKey": "0xabc...",
+  "message": "Store this private key securely..."
+}
+```
+
+<Warning>The `create-wallet` action returns the private key in the response body. Store it securely — it cannot be retrieved again.</Warning>
+
+#### Register wallet
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | string | Yes | `register-wallet` |
+| `agentId` | string | Yes | Agent identifier |
+| `companyId` | string | Yes | Company identifier |
+| `privateKey` | string | Yes | Existing private key to register |
+
+```json
+{
+  "success": true,
+  "agentId": "agent_123",
+  "companyId": "company_456",
+  "address": "0x1234...abcd"
+}
+```
+
+#### Make payment
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | string | Yes | `make-payment` |
+| `agentId` | string | Yes | Agent identifier |
+| `url` | string | Yes | Payment endpoint URL |
+| `method` | string | No | HTTP method (default: `POST`) |
+| `headers` | object | No | Additional request headers |
+| `body` | object | No | Request body |
+
+```json
+{
+  "success": true,
+  "result": {}
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid action or missing required fields |
+| 401 | Unauthorized |
+| 402 | Payment failed |
+| 404 | Wallet not found |
+| 500 | Internal error |
+
+## Agent files
+
+```http
+GET /api/files
+POST /api/files
+DELETE /api/files
+```
+
+Upload, list, and delete files associated with agents. Files are stored on disk and tracked in the database. All requests require session authentication.
+
+### List files
+
+```http
+GET /api/files?agentId=agent_123
+```
+
+#### Query parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agentId` | string | No | Filter files by agent |
+
+#### Response
+
+```json
+{
+  "files": [
+    {
+      "id": "file_123",
+      "filename": "data.csv",
+      "url": "/api/files/download?id=file_123",
+      "size": 1234,
+      "mimeType": "text/csv",
+      "agentId": "agent_123",
+      "createdAt": "2026-03-19T00:00:00Z"
+    }
+  ],
+  "totalSize": 1234,
+  "count": 1
+}
+```
+
+### Upload file
+
+```http
+POST /api/files
+```
+
+Uploads a file using `multipart/form-data`.
+
+#### Form fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | File | Yes | The file to upload |
+| `agentId` | string | Yes | Agent to associate the file with. Must belong to the authenticated user. |
+
+#### Response (201 Created)
+
+```json
+{
+  "success": true,
+  "file": {
+    "id": "file_123",
+    "name": "data.csv",
+    "size": 1234,
+    "type": "text/csv",
+    "url": "/api/files/download?id=file_123",
+    "uploaded": "2026-03-19T00:00:00Z"
+  }
+}
+```
+
+#### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | No file uploaded, or `agentId` is required |
+| 401 | Unauthorized |
+| 404 | Agent not found |
+| 413 | Storage limit exceeded. The default per-user storage limit is 10 MB. |
+| 500 | Failed to upload file |
+
+### Delete file
+
+```http
+DELETE /api/files
+```
+
+#### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fileId` | string | Yes | File identifier |
+
+#### Response
+
+```json
+{
+  "success": true,
+  "fileId": "file_123"
+}
+```
+
+#### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | `fileId` is required |
+| 401 | Unauthorized |
+| 404 | File not found |
+| 500 | Failed to delete file |
+
 ## Send message
 
 ```http

diff --git a/api-reference/health.mdx b/api-reference/health.mdx
@@ -124,10 +124,16 @@
 ## Get heartbeat settings
 
 ```http
-GET /api/heartbeat
+GET /api/heartbeat?agentId=agent_123
 ```
 
-Requires session authentication.
+Requires session authentication. Returns the heartbeat schedule for a specific agent. Heartbeat settings control how frequently the agent wakes up to perform autonomous actions.
+
+### Query parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agentId` | string | Yes | Agent identifier |
 
 ### Response
 
@@ -136,58 +142,85 @@
   "heartbeat": {
     "frequency": "3h",
     "enabled": true,
-    "lastHeartbeat": "2026-03-19T00:00:00Z",
-    "nextHeartbeat": "2026-03-19T03:00:00Z"
-  },
-  "message": "Heartbeat scheduling database integration pending"
+    "lastHeartbeat": null,
+    "nextHeartbeat": null
+  }
 }
 ```
 
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | `agentId` is required |
+| 401 | Unauthorized |
+
 ## Update heartbeat settings
 
 ```http
 POST /api/heartbeat
 ```
 
-Requires session authentication.
+Requires session authentication. Configures the heartbeat schedule for an agent. The `nextHeartbeat` is calculated automatically from the current time plus the parsed frequency.
 
 ### Request body
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `frequency` | string | No | Heartbeat interval (for example, `3h`) |
-| `enabled` | boolean | No | Enable or disable heartbeats |
+| `agentId` | string | Yes | Agent identifier. Must belong to the authenticated user. |
+| `frequency` | string | No | Heartbeat interval using the format `{number}{unit}` where unit is `m` (minutes), `h` (hours), or `d` (days). Examples: `30m`, `3h`, `1d`. Defaults to `3h`. |
+| `enabled` | boolean | No | Enable or disable heartbeats. Defaults to `true`. |
 
 ### Response
 
 ```json
 {
-  "frequency": "3h",
-  "enabled": true,
-  "lastUpdated": "2026-03-19T00:00:00Z",
-  "lastHeartbeat": "2026-03-19T00:00:00Z",
-  "nextHeartbeat": "2026-03-19T03:00:00Z",
-  "message": "Heartbeat settings will persist to database once integration is complete"
+  "heartbeat": {
+    "frequency": "3h",
+    "enabled": true,
+    "lastHeartbeat": "2026-03-19T00:00:00Z",
+    "nextHeartbeat": "2026-03-19T03:00:00Z",
+    "lastUpdated": "2026-03-19T00:00:00Z"
+  }
 }
 ```
 
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | `agentId` is required |
+| 401 | Unauthorized |
+| 500 | Failed to update heartbeat settings |
+
 ## Delete heartbeat settings
 
 ```http
 DELETE /api/heartbeat
 ```
 
-Requires session authentication. Resets heartbeat configuration to defaults.
+Requires session authentication. Removes the heartbeat settings for an agent.
+
+### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `agentId` | string | Yes | Agent identifier |
 
 ### Response
 
 ```json
 {
-  "success": true,
-  "message": "Heartbeat settings reset - database cleanup will occur once integration is complete"
+  "success": true
 }
 ```
 
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 401 | Unauthorized |
+
 ## Container health checks
 
 Agent containers run the official OpenClaw image, which exposes built-in health endpoints on port `18789`. The backend uses these to determine container readiness during provisioning and ongoing monitoring.
@@ -198,7 +231,7 @@

 | Endpoint | Purpose | Description |
 |----------|---------|-------------|
 | `GET /healthz` | Liveness | Returns `200` when the gateway process is running. Used by Docker's `HEALTHCHECK` to detect crashed or hung containers. |
 | `GET /readyz` | Readiness | Returns `200` when the gateway is ready to accept requests. Use this to verify the container has completed startup before routing traffic. |

 Both endpoints are unauthenticated and bind to the container's internal port (`18789`).

diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx
@@ -1,11 +1,11 @@
 ---
 title: API reference
 description: "Complete API reference for Agentbot"
 ---

 # API reference

 Complete API reference for Agentbot.

 ## Base URL

@@ -15,7 +15,7 @@

 ## Authentication

 Agentbot supports multiple authentication methods depending on the endpoint.

 ### Session authentication

@@ -198,6 +198,11 @@
 | `/api/installations` | GET | List registered installations (backend only, requires identity headers) |
 | `/api/agent` | GET | Agent interaction (health, sessions, memory, skills, credentials) |
 | `/api/agent` | POST | Agent interaction (chat, create-session, update-skill, set-credential) |
+| `/api/agent/mpp` | GET | MPP wallet actions (list-wallets, get-wallet, get-balance) |
+| `/api/agent/mpp` | POST | MPP wallet actions (create-wallet, register-wallet, make-payment) |
+| `/api/files` | GET | List agent files |
+| `/api/files` | POST | Upload a file to an agent (multipart/form-data) |
+| `/api/files` | DELETE | Delete an agent file |
 | `/api/settings` | GET | Get current user profile |
 | `/api/settings` | POST, PATCH | Update user profile |
 | `/api/settings/password` | POST | Change password |
@@ -207,8 +212,8 @@
 | `/api/auth/reset-password` | POST | Reset password |
 | `/api/security/risc` | GET | Cross-Account Protection endpoint health check |
 | `/api/security/risc` | POST | Receive Google Cross-Account Protection (RISC) security events |
 | `/api/auth/farcaster/verify` | GET, POST | Verify Farcaster identity (GET returns endpoint metadata) |
 | `/api/auth/farcaster/refresh` | GET, POST | Refresh Farcaster token (GET returns endpoint metadata) |
 | `/api/auth/token-gating/verify` | GET, POST | Verify token gating access |
 | `/api/dashboard/cost` | GET | Get aggregated cost dashboard data (by agent, model, and day) |
 | `/api/billing` | GET | Get billing info |
@@ -218,8 +223,8 @@
 | `/api/scheduled-tasks` | POST | Create a scheduled task |
 | `/api/scheduled-tasks` | PUT | Update a scheduled task |
 | `/api/scheduled-tasks` | DELETE | Delete a scheduled task |
 | `/api/stripe/checkout` | GET | Redirect to Stripe checkout (accepts `plan` query param: `solo`, `collective`, `label`, `network`). Prices are in GBP. |
 | `/api/stripe/credits` | GET | Redirect to Stripe credit purchase (accepts `price` query param) |
 | `/api/stripe/storage-upgrade` | POST | Upgrade storage plan |
 | `/api/metrics/:userId/historical` | GET | Get historical time-series metrics (backend only) |
 | `/api/metrics/:userId/performance` | GET | Get current performance metrics (backend only) |
@@ -243,11 +248,11 @@
 | `/api/openclaw/instances/:id/stats` | GET | Get instance container stats (backend only, requires auth) |
 | `/api/deployments` | POST | Deploy an agent container (backend only, requires auth) |
 | `/api/models` | GET | List available OpenRouter AI models |
 | `/api/basefm/live` | GET | List active Mux live streams |
 | `/api/basefm/streams` | POST | Create a Mux live stream (RAVE token-gated) |
 | `/api/generate-video` | POST | Generate and upload a video (requires session) |
 | `/api/webhooks/mux` | POST | Mux webhook receiver (signature-verified) |
 | `/api/webhooks/resend` | POST | Resend inbound email webhook (signature-verified, sender allowlist) |
 | `/api/mission-control/fleet/graph` | GET | Get agent fleet constellation graph |
 | `/api/mission-control/fleet/traces` | GET | Get real-time execution traces |
 | `/api/mission-control/fleet/costs` | GET | Get per-agent cost attribution |
@@ -285,7 +290,7 @@

 ## SDK

 Use the Agentbot SDK:

 ```bash
 npm install @agentbot/sdk