> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofable.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Talk to your agent from any app

> Call your agent from any app or server with one request, and check the records behind every answer it gives.

Your agent runs on Proofable, so there is nothing to deploy and no machine to keep. Any app, server, or runtime talks to it with one call. It answers as itself, inside the limits you signed, and cites the records it read.

## One call

```javascript theme={"system"}
import { ProofableClient } from '@proofable/sdk';

const client = new ProofableClient({ apiKey: process.env.PROOFABLE_ACCESS_KEY });

const turn = await client.agentChat({
  agentId: 'my-agent',
  messages: [{ role: 'user', content: 'Summarize this week for the client.' }],
  onEvent: (type, data) => {
    if (type === 'answer.delta') process.stdout.write(data.text);
  },
});

turn.answer;     // the agent's answer
turn.citations;  // the records it read
turn.credits;    // what the turn spent
```

Sign the client in with an [access key](https://docs.proofable.me/deployment/access-keys.md) on a server, or with the signed-in person's session in a browser. Never ship an access key in browser code.

## Let your app's users talk to your agent

Sign your users in with Proofable, then make the same call as them. Each person talks to your public agent inside their own Proofable profile, with their records and nothing of yours in the conversation. What the agent knows is its instructions and the records you made public. Your app pays.

```javascript theme={"system"}
import { ProofableClient, ProofableSignIn } from '@proofable/sdk';

// clientId: what register() returned the first time, kept with your app's settings.
const signIn = new ProofableSignIn({ redirectUri: 'https://your.app/proofable/callback', clientId: settings.proofableClientId });

// 1. Send the person to Proofable. Keep `state` and `verifier` until they are back; a signed cookie works.
const started = await signIn.start();
redirect(started.url);

// 2. They are back at your callback with `code` and `state` in the URL.
const tokens = await signIn.finish({ code: query.code, verifier: kept.verifier, state: query.state, expectedState: kept.state });

// 3. Act as the person, billed to your app.
const person = new ProofableClient({
  apiKey: tokens.accessToken,
  appId: 'your-app',
  billingWallet: '0xYourAccount',
  appOrigin: 'https://your.app',
});
const who = await person.me();                                     // { handle, address, ... }
const turn = await person.agentChat({
  agentId: 'my-agent',
  agentWallet: '0xYourAccount',                                    // your account: the agent runs in the person's own profile
  turnId: `u-${yourUserKey}-${Date.now()}`,                        // your key for the person; every spend record carries it
  messages: [{ role: 'user', content: 'Where does the case start?' }],
});
```

**Sign-in** is the one every MCP host uses ([MCP OAuth](https://docs.proofable.me/mcp/oauth.md)). `start()` with no `clientId` registers your callback and returns the id; store it with your app's settings and pass it to every later instance. Renew with `signIn.refresh(tokens.refreshToken)` before the token expires.

**Who pays.** Your app does. Turn it on once, signed in as yourself:

```bash theme={"system"}
npx -y @proofable/sdk sponsor --app your-app --origin https://your.app --credits-per-day 2000
```

From then on a client built with `appId` and `billingWallet` carries your sponsorship. Your organization pays for your users' checks and their chats with your agents, within the daily cap you set, and every spend record names your app and your `turnId`, so limits per person are yours to apply. Without `appId` and `billingWallet`, each person spends their own credits. In code, the same step is `client.sponsorApp({ appId, origin, creditsPerDay })`.

**What the agent may do** for the person is fixed. It can read and add to the person's own records, and search the web. It cannot spend, grant, change keys or run code, and a high-risk action is refused. The agent must be public or link-only on your account. When it keeps words the person confirms, the record is the person's own, and they can open it at `proofable.me/proof/<qHash>`. Keeping it is one credit from the person's own allowance, which every account has; the turns are what your app pays.

## What happens on each turn

1. Proofable finds the [permission](https://docs.proofable.me/agents/agent-delegation.md) you signed for the agent. With none, the turn runs only if `agentWallet` names someone else's public agent, in your own profile, under the fixed rule above.
2. The turn runs as the agent: its own instructions and skills from its [identity](https://docs.proofable.me/agents/agent-identity.md), and, for your own agent, the connected apps you bound to it.
3. Every tool call is checked before it runs, against the permission or the fixed rule, read again for each call. Revoke the permission and the next call stops, in every app that talks to the agent.
4. The answer comes back with the records the agent read. Each one opens at `proofable.me/proof/<qHash>`, so anyone you share it with can check where the answer came from.

## Over HTTP

`POST https://api.proofable.me/api/v1/agent/chat/turn` with `Authorization: Bearer <token>` streams the turn as Server-Sent Events.

```bash theme={"system"}
curl -N https://api.proofable.me/api/v1/agent/chat/turn \
  -H "Authorization: Bearer $PROOFABLE_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"my-agent","messages":[{"role":"user","content":"What changed today?"}]}'
```

| Field | What it does |
| - | - |
| `agentId` | Run the turn as this agent. Omit it to run as yourself. |
| `agentWallet` | The agent's account: when two of your agents share an id, or to talk to someone else's public agent, which then runs in your own profile |
| `messages` | The conversation, `user` and `assistant` turns, ending with the user |
| `systemPrompt` | Context from your app. The agent reads it as data, after its own instructions. |
| `model` | `default` or `advanced`. With `provider`, that provider's model id. |
| `provider`, `providerSecretProofQHash` | Run on your own model key from the vault instead of hosted inference |

The stream sends `turn.start`, `answer.delta` as the answer arrives, `tool.start` and `tool.result` for each call, and ends with one `final` event:

```json theme={"system"}
{
  "outcome": "succeeded",
  "answer": "…",
  "citations": [{ "qHash": "0x…", "title": "Chapter 1", "facet": "memory", "visibility": "public" }],
  "agent": { "agentId": "my-agent", "agentWallet": "0x…", "identityQHash": "0x…", "delegationQHash": "0x…" },
  "credits": { "spent": 2 }
}
```

For someone else's public agent, `delegationQHash` is `null`. There is no permission between you, and the agent ran in your own profile.

A request Proofable refuses never opens the stream. It answers JSON with the reason:

| Status | Code | Why |
| - | - | - |
| 401 | `AUTH_REQUIRED` | No session, OAuth token, or access key |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits for a hosted turn, on the account that pays |
| 402 | `SPONSOR_CAP_EXCEEDED` | The sponsoring app has used its daily cap |
| 403 | `AGENT_DELEGATION_REQUIRED` | No active permission from your account to this agent, and no public agent of that id at `agentWallet` |
| 403 | `SPONSOR_GRANT_INVALID` | The app's sponsor grant was sent but not accepted because it expired, was already used, was for another app or origin, or was for an agent that is not the sponsoring account's. The person is never charged instead |
| 403 | `ADVANCED_REQUIRES_PRO` | Advanced runs on paid plans |

## What it costs

A hosted turn spends credits from the account that calls it, by the tokens it used and the model that served them, the same rate as a [job](https://docs.proofable.me/jobs.md) step. A turn your app sponsors spends the app owner's credits instead, within the app's daily cap. A turn on your own model key spends no credits for tokens; the [tool calls that reach another service](https://docs.proofable.me/pricing.md#what-a-tool-call-costs) cost the same on any model or key. See [pricing](https://docs.proofable.me/pricing.md).

Read your balance and spend at any time, by line and by day:

```javascript theme={"system"}
const { credits, usage } = await client.getUsage({ from: '2026-11-01', to: '2026-11-30' });
usage.summary.debitedByDay; // { '2026-11-01': 14, … }
```

Over HTTP it is `GET /api/v1/profile/usage?from=YYYY-MM-DD&to=YYYY-MM-DD` with the same token. In an MCP client, `proofable_context` carries the balance.

## Other ways to reach the same agent

* **In an MCP client.** `npx -y @proofable/sdk mount my-agent --apply claude` loads the agent into your client, Hermes, OpenClaw, or OpenCode. [Connect agent context](https://docs.proofable.me/agents/runtime-mount.md)
* **As background work.** Start a [job](https://docs.proofable.me/jobs.md) for scheduled or long work, on an isolated computer when it needs one.

## Related

* [Agent permissions](https://docs.proofable.me/agents/agent-delegation.md)
* [Agent identity](https://docs.proofable.me/agents/agent-identity.md)
* [Import an agent](https://docs.proofable.me/agents/import.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.