# Quickstart

Get an agent wallet funded and making payments in under five minutes.

***

## Prerequisites

* A FervusAI account and organisation. [Sign up at fervus.ai](https://fervus.ai)
* An API key from the dashboard under **Settings → API Keys**
* USDC deposited to your organisation balance (see [Funding](https://docs.fervusai.com/core-concepts/funding))

***

## Step 1 - Install the SDK

```bash
npm install @fervusai/sdk
```

```bash
pip install fervusai
```

***

## Step 2 - Create a spending policy

Before provisioning a wallet, define the rules it will operate under. You can do this in the dashboard under **Policies → New Policy**, or via the API:

```typescript
import { FervusAI } from "@fervusai/sdk";

const client = new FervusAI({ apiKey: process.env.FERVUS_API_KEY });

const policy = await client.policies.create({
  name: "Conservative - Research Agent",
  maxPerTx: "5.00",
  maxPerDay: "50.00",
  maxPerMonth: "500.00",
  velocityCap: 20,
  allowedRecipients: ["api.perplexity.ai", "api.tavily.com"],
});

console.log(policy.id); // pol_...
```

→ See [Spending Policies](https://docs.fervusai.com/core-concepts/spending-policies) for all policy parameters.

***

## Step 3 - Provision a wallet

```typescript
const wallet = await client.wallets.create({
  agentId: "agent_research_v2",
  label: "Research Agent - Market Data",
  ownerOrg: "org_7x2k",
  policyId: policy.id,
});

console.log(wallet.solanaAddress); // The agent's on-chain wallet address
console.log(wallet.usdcBalance);   // "0.00" - funded in the next step
```

Wallet provisioning settles in under one second. The `solanaAddress` is a PDA - a deterministic, program-controlled address derived from your organisation ID and agent ID.

***

## Step 4 - Fund the wallet

Allocate USDC from your organisation balance to the agent wallet:

```typescript
const funding = await client.wallets.fund({
  walletId: wallet.id,
  amount: "100.00",
  currency: "USDC",
});

console.log(funding.usdcBalance); // "100.00"
```

Or fund directly from the dashboard: **Wallets → \[wallet name] → Fund Wallet**.

***

## Step 5 - Send a payment

```typescript
const tx = await wallet.pay({
  to: "api.perplexity.ai",
  amount: "2.50",
  currency: "USDC",
  memo: "Perplexity query batch #8821",
});

console.log(tx.signature);  // Solana transaction signature
console.log(tx.status);     // "confirmed"
console.log(tx.onChainSlot); // Solana slot number
```

If the payment violates the attached policy - amount over `maxPerTx`, recipient not in `allowedRecipients`, daily cap exceeded - it will be **rejected before the transaction is submitted to Solana**. A `transaction.blocked` event will fire on your webhook.

***

## Step 6 - Receive events via webhook

Register a webhook endpoint to receive real-time events:

```typescript
const webhook = await client.webhooks.create({
  url: "https://your-server.com/fervus-events",
  events: [
    "transaction.completed",
    "transaction.blocked",
    "balance.low",
  ],
});
```

Your server will receive POST requests for each event:

```json
{
  "event": "transaction.completed",
  "wallet_id": "wal_...",
  "tx_signature": "5KtP...",
  "amount": "2.50",
  "recipient": "api.perplexity.ai",
  "policy_triggered": false,
  "on_chain_slot": 321847293,
  "timestamp": "2026-04-29T12:00:00Z"
}
```

→ See [Webhooks](https://docs.fervusai.com/api-reference/webhooks) for the full event catalogue.

***

## What's next

* [Agent Wallets](https://docs.fervusai.com/core-concepts/agent-wallets) - understand the PDA model and wallet isolation
* [Spending Policies](https://docs.fervusai.com/core-concepts/spending-policies) - all policy parameters and enforcement behaviour
* [Agent-to-Agent Payments](https://docs.fervusai.com/core-concepts/a2a-payments) - pay other agents with escrow
* [TypeScript SDK](https://docs.fervusai.com/sdk/typescript) - full SDK reference
* [Python SDK](https://docs.fervusai.com/sdk/python) - full SDK reference


---

# 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/getting-started/quickstart.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.