Complete reference for the OpenAgents API endpoints.
This API reference provides details of all available endpoints in the OpenAgents API. Select a specific API section from the sidebar to view detailed documentation for that area.
Beta Warning: The OpenAgents API is currently in beta. Do not use it with live funds that you aren't willing to lose. The API may change without notice and we cannot guarantee its stability during this phase.
Agents are AI-powered entities that can perform tasks on behalf of users. You can create, list, and manage agents through these endpoints.
Each agent can have its own wallet to send and receive payments. Agent payments support creating invoices, paying invoices, and checking balances.
This section contains details about the data structures used in API requests and responses.
| Property | Type | Required | Description |
|---|---|---|---|
| balance_sats | string | No | The wallet balance in satoshis |
| token_balances | object | No | Balances of any tokens held by the wallet |
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | No | The unique identifier for the Agent instance |
| user_id | string | No | The ID of the user who owns this agent |
| name | string | No | The user-friendly name of the agent |
| status | string | No | The agent status (e.g., idle, running, stopped) |
| configuration | object | No | The agent configuration (LLM settings, prompts, etc.) |
| spark_address | string | No | The public Spark address for receiving payments (if wallet exists) |
| identity_public_key | string | No | The identity public key associated with the Spark wallet (if wallet exists) |
| wallet_status | string | No | The status of the agent's wallet |
| created_at | string (date-time) | No | When the agent was created |
| updated_at | string (date-time) | No | When the agent was last updated |
| Property | Type | Required | Description |
|---|---|---|---|
| agent_id | string | No | The unique identifier for the Agent instance |
| spark_address | string | No | The public Spark address for receiving payments |
| identity_public_key | string | No | The identity public key associated with the Spark wallet |
| wallet_status | string | No | The status of the agent's wallet |
| Property | Type | Required | Description |
|---|---|---|---|
| amount_sats | integer | Yes | Amount in satoshis to request |
| memo | string | No | Optional description for the invoice |
| expiry | integer | No | Optional expiry time in seconds |
| Property | Type | Required | Description |
|---|---|---|---|
| amount_sats | integer | Yes | Amount to send in satoshis |
| recipient_agent_id | string | No | Agent ID to send payment to |
| external_address | string | No | External spark address to send to |
| lightning_invoice | string | No | Lightning invoice to pay |
| memo | string | No | Optional memo for the payment |
| max_fee_sats | integer | No | Maximum fee to pay in satoshis |
| Property | Type | Required | Description |
|---|---|---|---|
| invoice | string | Yes | The Lightning invoice to pay |
| max_fee_sats | integer | Yes | Maximum fee to pay in satoshis |
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The user-friendly name of the agent |
| configuration | object | No | The agent configuration (LLM settings, prompts, etc.) |
| Property | Type | Required | Description |
|---|---|---|---|
| invoice | string | No | The encoded Lightning invoice |
| payment_hash | string | No | The payment hash for this invoice |
| amount_sats | integer | No | The amount requested in satoshis |
| status | string | No | The status of the invoice |
| expires_at | integer | No | When this invoice expires (Unix timestamp) |
| Property | Type | Required | Description |
|---|---|---|---|
| payment_id | string | No | The internal payment ID |
| status | string | No | The status of the payment |
| amount_paid_sats | string | No | The amount paid in satoshis |
| fee_paid_sats | string | No | The fee paid in satoshis |
| preimage | string | No | The payment preimage |
| failure_reason | string | No | The reason for payment failure if applicable |