# ElizaOS

SpriusAI gives your Eliza agents a sovereign vault, a USDC balance, and the ability to settle payments on-chain — governed by spending policy from the moment of provisioning. Integrate by registering custom actions that call the SpriusAI HTTP API.

***

## Configuration

Set the following environment variables for your Eliza agent:

| Variable           | Description                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| `SPRIUS_API_KEY`   | Your SpriusAI API key                                                             |
| `SPRIUS_WALLET_ID` | Wallet ID to use. If unset, provision one via `POST /v1/wallets` before starting. |

***

## Provisioning a wallet

If you don't have a wallet yet, create one before configuring your agent:

```bash
curl -X POST https://api.spriusai.com/v1/wallets \
  -H "Authorization: Bearer $SPRIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "my-eliza-agent",
    "label": "My Eliza Agent",
    "policyId": "pol_conservative"
  }'
```

Note the `wallet_id` from the response and set it as `SPRIUS_WALLET_ID`.

***

## Registering payment actions

Add SpriusAI payment actions to your Eliza runtime:

```typescript
import { AgentRuntime, Action, IAgentRuntime, Memory, State } from "@elizaos/core";

const BASE = "https://api.spriusai.com/v1";
const apiKey = process.env.SPRIUS_API_KEY!;
const walletId = process.env.SPRIUS_WALLET_ID!;
const headers = { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" };

const payAction: Action = {
  name: "PAY",
  description: "Send a USDC payment from the agent's SpriusAI wallet.",
  similes: ["SEND_PAYMENT", "PAY_USDC", "TRANSFER"],
  validate: async (_runtime: IAgentRuntime, message: Memory) => {
    return !!message.content.text?.toLowerCase().includes("pay");
  },
  handler: async (_runtime: IAgentRuntime, message: Memory, _state: State, options: Record<string, string>) => {
    const res = await fetch(`${BASE}/payments`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        walletId,
        to: options.to,
        amount: options.amount,
        currency: "USDC",
        memo: options.memo,
      }),
    });
    const tx = await res.json();
    return `Payment of $${options.amount} USDC confirmed. Transaction: ${tx.txSignature}`;
  },
  examples: [],
};

const checkBalanceAction: Action = {
  name: "CHECK_BALANCE",
  description: "Query the agent's current USDC balance.",
  similes: ["BALANCE", "GET_BALANCE"],
  validate: async (_runtime, message) => {
    return !!message.content.text?.toLowerCase().includes("balance");
  },
  handler: async () => {
    const res = await fetch(`${BASE}/wallets/${walletId}`, { headers });
    const wallet = await res.json();
    return `Current balance: $${wallet.balance} USDC`;
  },
  examples: [],
};

const agent = new AgentRuntime({
  // ... your existing Eliza config
  actions: [payAction, checkBalanceAction],
});
```

***

## Available actions

| Action              | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| `PAY`               | Send a USDC payment — calls `POST /v1/payments`                     |
| `CHECK_BALANCE`     | Query current balance — calls `GET /v1/wallets/{id}`                |
| `LIST_TRANSACTIONS` | Retrieve recent history — calls `GET /v1/wallets/{id}/transactions` |
| `PAY_AGENT`         | Initiate A2A escrow — calls `POST /v1/payments/a2a`                 |

***

## Example: research agent with paid API calls

```typescript
// In the PAY handler, after confirming payment, proceed to call the paid API:
handler: async (_runtime, _message, _state, options) => {
  // 1. Pay for access
  const payRes = await fetch(`${BASE}/payments`, {
    method: "POST",
    headers,
    body: JSON.stringify({ walletId, to: "api.perplexity.ai", amount: "2.50", currency: "USDC" }),
  });
  const tx = await payRes.json();

  // 2. Use the paid service
  const queryRes = await fetch("https://api.perplexity.ai/search", {
    headers: { "Authorization": `Bearer ${process.env.PERPLEXITY_API_KEY}` },
    body: JSON.stringify({ query: options.query }),
  });

  return `Payment confirmed (${tx.txSignature}). Results: ${await queryRes.text()}`;
},
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spriusai.com/integrations/elizaos.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.