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

# Agent Create

> Create or import an agent on your profile, with an optional dedicated spend account.

The agent links to your Proofable profile and defaults to your signed-in account. Add a separate spend account and limits only when you need them.

| Step | Action |
| - | - |
| 1 | **`proofable_agent_link`** with **`agentId`** and **`agentWallet`** (use the signed-in account from **`proofable_context`** unless you already have a dedicated account) |
| 2 | **`proofable_agent_create`** with the same stable identifiers |
| 3 | Follow the returned **`next_action`** exactly |
| 4 | **`proofable_agent_link`** until **`linked: true`** |

Leave out **`controllerWallet`** when the signed-in account from **`proofable_context`** should own the agent.

Ask:

> Create or import an agent on my Proofable profile. Give it a separate spend account if it needs one. Set spend and action limits. Then confirm it is ready.

To import, inspect a package, repo, or card with the [agent import](https://docs.proofable.me/agents/import.md) HTTP routes, then call **`proofable_agent_create`** with the mapped fields.

## Account options

### Signed-in profile (default)

Omit **`agentWallet`**. The agent lives on your signed-in account. Identity is enough. Several agents on one account need **`agentId`** on every link and mount call.

### Dedicated account

The private key stays in your wallet or secure runtime, and Proofable only ever receives the public address. Create the account there, then pass that address as **`agentWallet`**.

```json theme={"system"}
{
  "agentId": "data-analyst",
  "agentWallet": "0xAgent...",
  "delegationAllowedActions": ["read_context", "read_proofs"],
  "delegationDeniedActions": ["send_message"],
  "delegationRuntimePolicy": { "requiresHumanApproval": true },
  "maxSpend": "15000000"
}
```

Use a dedicated account when you want independent spend, revocation, or offboarding without touching your profile account.

### Bring an existing account

Pass an existing **`agentWallet`**. The agent account signs identity. The approving profile signs spend and action limits.

When the signed-in account does not control that key:

1. Sign and submit the returned identity step with the agent key. **`proofable_verify`** returns the identity **`qHash`**.
2. Repeat **`proofable_agent_create`** with the same arguments plus **`identityQHash`** set to that value. The returned step carries this call as **`thenCall`**.
3. The approving account completes permissions in-session or through the returned hosted URL.

A controller session cannot self-attest for a different agent account, so identity always comes first. The identity record lives on the agent account, which no permission names yet; **`identityQHash`** is how the approving session finds it, and the permission is recorded only after the identity exists. **`proofable_agent_link`** accepts **`identityQHash`** for the same reason.

## What each result means

Every non-validation result includes **`path`** and **`next_action`**.

| `path` | Meaning | `next_action` |
| - | - | - |
| `already_linked` | Identity and the permissions this account needs already exist | `ready` |
| `session_auto_complete` | Signed-in session completed the missing step(s) | `call_proofable_agent_link` |
| `signatures_required` | A signature is still required | `submit_remaining_signatures` |
| `hosted_required` | Browser handoff is required | `open_hosted_verify` |
| `payment_required` | The account paying for the current step needs more credits | `complete_billing_then_retry` |

**`sessionProgress.identityComplete`**, **`delegationRequired`**, and **`delegationComplete`** show which step is required and already saved. On **`payment_required`**, add credits and retry the same request.

## Hosted callback

Use the SDK helper instead of assembling query strings:

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

const url = getHostedAgentCreateUrl({
  agentId: 'data-analyst',
  agentWallet,
  controllerWallet,
  identityQHash, // required here because the accounts differ
  allowedActions: ['read_context', 'read_proofs'],
  deniedActions: ['send_message'],
  runtimePolicy: { requiresHumanApproval: true },
  returnUrl: 'https://app.example.com/agents/callback',
});
```

With **`identityQHash`**, Hosted Verify requests only permissions. The callback receives the new permission **`qHash`**, **`agentId`**, and **`agentWallet`**. Keep the identity **`qHash`** from step 1.

Keep agent setup, login and gate checkout on separate URLs:

* Login: **`intent=login&returnUrl=...`**
* Gate checkout: **`gateId=...&returnUrl=...`**
* Agent setup: **`getHostedAgentCreateUrl(...)`**

## Billing

Billing follows the signer for each proof unless a validated sponsor or pay-per-call proof overrides it:

* Agent identity: the **agent account** pays.
* Permissions (separate spend account only): the **approving profile** pays.
* Hosted completion: the signed-in account pays for the step it signs.
* Sponsor grant or pay-per-call: the validated sponsor/caller pays.

Hosted sign-in itself is free. See [Pricing](https://docs.proofable.me/pricing.md).

Optional fields include **`instructions`**, **`skills`**, **`services`**, expiry, spend cap, runtime policy, approval policy, and allowed/denied actions. See [Agent identity](https://docs.proofable.me/agents/agent-identity.md) and [Agent delegation](https://docs.proofable.me/agents/agent-delegation.md).


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