# persona.energy

Source-grounded persona service for agents and applications.

Base API: https://api.persona.energy
Web: https://persona.energy
Default public seed persona: paul-graham

Public personas are advisor_lens resources, not literal impersonations. Do not
present a public persona as literally being the target person.

## Auth and payment

Preferred auth is an API key:

```bash
persona login
persona account
```

API keys start with pxk_. Authenticated calls charge the server wallet returned
from GET /account. The account page and clients should display and fund only
server_wallet_address from /account.

Anonymous or BYO-wallet calls use mppx HTTP 402 challenge-response. Do not build
manual ERC-20 transfers for mppx calls.

## Core endpoints

```
GET  /personas
GET  /personas/:slug
GET  /personas/:slug/versions
POST /personas/:slug/retrieve
POST /personas/:slug/ask
POST /personas/:slug/feedback
POST /personas/:slug/eval
GET  /account
POST /account/api-keys
GET  /account/api-keys
GET  /account/usage
POST /account/deposit-addresses
POST /auth/device
POST /auth/device/token
POST /auth/device/confirm
GET  /mcp
POST /mcp
```

## Ask example

```bash
curl -s https://api.persona.energy/personas/paul-graham/ask \
  -H "Authorization: Bearer pxk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"How should I get first users?","session_id":"new","require_evidence":true}'
```

Always preserve response.session_id for continuity. Inspect confidence, stance,
caveats, evidence, persona.version, message_id, cost, and receipt.

## MCP

```json
{
  "persona": {
    "url": "https://api.persona.energy/mcp",
    "headers": { "Authorization": "Bearer pxk_YOUR_KEY" }
  }
}
```

Tools: persona.list, persona.get, persona.ask, persona.retrieve,
persona.feedback, persona.eval, persona.account.

## CLI

```bash
persona personas
persona ask paul-graham "How should I get first users?" --json
persona retrieve paul-graham "doing things that do not scale" --json
persona feedback SESSION_ID MESSAGE_ID --rating good --notes "grounded"
persona eval paul-graham
```