# ElizaOS

FervusAI provides a first-party ElizaOS plugin that gives your Eliza agents a wallet, a USDC balance, and the ability to pay for services on-chain.

***

## Installation

```bash
npm install @fervusai/eliza-plugin
```

***

## Configuration

Add the plugin to your Eliza agent configuration:

```typescript
import { FervusAIPlugin } from "@fervusai/eliza-plugin";

const agent = new AgentRuntime({
  // ... your existing Eliza config
  plugins: [
    new FervusAIPlugin({
      apiKey: process.env.FERVUS_API_KEY,
      walletId: process.env.FERVUS_WALLET_ID,
    }),
  ],
});
```

If `walletId` is omitted, the plugin will provision a new wallet on first run using the agent's name and ID as identifiers.

***

## What the plugin adds

The plugin registers the following actions and providers into your Eliza runtime:

### Actions

**`PAY`** - Send a USDC payment from the agent's wallet.

```
User: Pay $2.50 to api.perplexity.ai for the search results
Agent: [executes PAY action] Payment of $2.50 USDC confirmed. Transaction: 5KtP...xyz
```

**`CHECK_BALANCE`** - Query the agent's current USDC balance.

```
User: What's your current balance?
Agent: [executes CHECK_BALANCE action] Current balance: $97.50 USDC
```

**`LIST_TRANSACTIONS`** - Retrieve recent transaction history.

**`PAY_AGENT`** - Initiate an A2A escrow payment to another agent.

### Providers

**`WalletProvider`** - Injects wallet context into the agent's memory at runtime. Provides current balance, recent transactions, and policy status so the agent can reason about its financial capacity.

***

## Environment variables

| Variable           | Description                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| `FERVUS_API_KEY`   | Your FervusAI API key                                                             |
| `FERVUS_WALLET_ID` | Wallet ID to use. If unset, a new wallet is provisioned.                          |
| `FERVUS_POLICY_ID` | Policy to attach when auto-provisioning a wallet. Defaults to `pol_conservative`. |

***

## Auto-provisioning

If `FERVUS_WALLET_ID` is not set, the plugin will call `client.wallets.create` on startup using:

* `agentId`: derived from your Eliza agent's `name` field
* `label`: `"{agent name} - ElizaOS"`
* `policyId`: `FERVUS_POLICY_ID` or `pol_conservative`

The created wallet ID is logged to stdout. Set it as `FERVUS_WALLET_ID` in subsequent runs to reuse the same wallet.

***

## Example: research agent with paid API calls

```typescript
import { FervusAIPlugin } from "@fervusai/eliza-plugin";
import { PerplexityPlugin } from "@elizaos/plugin-perplexity";

const agent = new AgentRuntime({
  name: "ResearchAgent",
  plugins: [
    new FervusAIPlugin({
      apiKey: process.env.FERVUS_API_KEY,
      walletId: process.env.FERVUS_WALLET_ID,
    }),
    new PerplexityPlugin({
      apiKey: process.env.PERPLEXITY_API_KEY,
      // FervusAI handles payment when the plugin requests it
      paymentProvider: "fervusai",
    }),
  ],
});
```


---

# 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.fervusai.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.