# Quickstart

Provision a funded agent vault and make your first on-chain payment in under five minutes.

***

## Prerequisites

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

***

## Step 1 — Create a spending policy

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

```bash
curl -X POST https://api.therosai.com/v1/policies \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conservative - Research Agent",
    "max_per_tx": "5.00",
    "max_per_day": "50.00",
    "max_per_month": "500.00",
    "velocity_cap": 20,
    "allowed_recipients": ["api.perplexity.ai", "api.tavily.com"]
  }'
```

```json
{
  "id": "pol_...",
  "name": "Conservative - Research Agent",
  "max_per_tx": "5.00",
  "max_per_day": "50.00",
  "max_per_month": "500.00"
}
```

→ See [Spending Policies](/core-concepts/spending-policies.md) for all policy parameters.

***

## Step 2 — Provision a vault

```bash
curl -X POST https://api.therosai.com/v1/wallets \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_research_v2",
    "label": "Research Agent - Market Data",
    "owner_org": "org_7x2k",
    "policy_id": "pol_..."
  }'
```

```json
{
  "id": "wal_...",
  "solana_address": "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwx",
  "usdc_balance": "0.00"
}
```

Provisioning settles in under one second. The `solana_address` is a PDA — a deterministic, program-controlled address derived from your organisation ID and agent ID. There is no private key.

***

## Step 3 — Fund the vault

Allocate USDC from your organisation balance to the agent vault:

```bash
curl -X POST https://api.therosai.com/v1/wallets/wal_.../fund \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "USDC"
  }'
```

```json
{
  "wallet_id": "wal_...",
  "usdc_balance": "100.00"
}
```

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

***

## Step 4 — Send a payment

```bash
curl -X POST https://api.therosai.com/v1/wallets/wal_.../pay \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "api.perplexity.ai",
    "amount": "2.50",
    "currency": "USDC",
    "memo": "Perplexity query batch #8821"
  }'
```

```json
{
  "signature": "5KtP...",
  "status": "confirmed",
  "on_chain_slot": 321847293
}
```

If the payment violates the attached policy — amount over `max_per_tx`, recipient not in `allowed_recipients`, daily cap exceeded — it is **rejected before the transaction reaches Solana**. A `transaction.blocked` event fires on your webhook and the on-chain record reflects zero state change.

***

## Step 5 — Receive events via webhook

Register a webhook endpoint to receive real-time events:

```bash
curl -X POST https://api.therosai.com/v1/webhooks \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/theros-events",
    "events": ["transaction.completed", "transaction.blocked", "balance.low"]
  }'
```

Your server receives 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](/api-reference/webhooks.md) for the full event catalogue.

***

## What's next

* [Agent Vaults](/core-concepts/agent-wallets.md) — the PDA model and vault isolation
* [Spending Policies](/core-concepts/spending-policies.md) — all policy parameters and enforcement behaviour
* [Agent-to-Agent Payments](/core-concepts/a2a-payments.md) — commission other agents with on-chain escrow
* [API Reference](/api-reference/authentication.md) — full API 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.therosai.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.