---
name: regent-protocol
description: Govern an AI agent's actions with Regent Protocol — register a verifiable agent identity, bound it with an on-chain spending mandate, authorize actions against the mandate before executing them, and log every action to a Solana-anchored audit trail.
---

# Using Regent Protocol

Regent Protocol gives an AI agent a verifiable identity (AgentID) bound to a
KYC-verified responsible party, bounds its authority with on-chain spending
mandates, and anchors every action to Solana as a tamper-evident audit trail.
Use this skill when an agent needs to move money or take governed actions with
cryptographic proof of accountability.

## Prerequisites (one-time, human steps)

These happen in the dashboard at https://web.regentprotocol.org and cannot be
done by the agent itself:

1. Sign up and complete identity verification (Settings → Start Identity
   Verification). A user DID is issued and anchored on Solana.
2. Register an agent (Agents → Register Agent) → yields an `agent_...` id.
3. Create a mandate bound to that agent (Mandates → Create Mandate) with
   per-transaction, daily, and monthly limits and a currency.
4. Create an API key (API Keys → Create API Key) → the `rgnt_...` value is
   shown once.

## Authentication

All REST requests go to `https://api.regentprotocol.org` with:

```
Authorization: Bearer rgnt_<api-key>
```

(`X-API-Key: rgnt_<api-key>` also works.) Every
`/v1/organizations/{org_id}/...` endpoint requires the org id to match the
key's org — this is enforced server-side.

Smoke test:

```bash
curl https://api.regentprotocol.org/v1/organizations/<org-id>/agents \
  -H "Authorization: Bearer rgnt_..."
```

200 with a JSON array means auth and org scoping both work. 401 = bad/expired
key; 403 `NOT_MEMBER` = key belongs to a different org.

## Core loop: authorize → act → audit

Never execute a governed action without an authorization. The pattern
(Python SDK — `pip install regent`, Python 3.11+):

```python
import asyncio
from decimal import Decimal
from regent import RegentClient, AuthorizeRequest, IngestEventRequest

async def main():
    async with RegentClient(
        base_url="https://api.regentprotocol.org",
        api_key="<REGENT_API_KEY>",
    ) as r:
        # 1. Ask the mandate for permission
        auth = await r.payment.authorize(
            mandate_id="<REGENT_MANDATE_ID>",
            request=AuthorizeRequest(amount=Decimal("25"), currency="USD"),
        )
        # 2. Your business logic here (call an exchange, sign a tx, ...)
        # 3. Log the action to the audit trail
        await r.audit.ingest_event(IngestEventRequest(
            event_id=f"action-{auth.jti}",
            agent_id="<REGENT_AGENT_ID>",
            event_type="action.completed",
            payload={"amount": "25", "currency": "USD",
                     "authorization_jti": auth.jti},
        ))

asyncio.run(main())
```

Keep the `jti` from the authorization and reference it in the audit event —
that is what ties the action to its permission.

## Handling denials

Every non-2xx response has the shape:

```json
{"detail": {"code": "LIMIT_EXCEEDED", "message": "...", "authorization_id": "..."}}
```

Codes the agent must expect and respect:

- `LIMIT_EXCEEDED` — the amount exceeds a per-transaction, daily, monthly, or
  per-entity limit. Do not retry with the same amount; surface to the operator.
- `AGENT_NOT_ACTIVE` / `MANDATE_SUSPENDED` — the agent was revoked (kill
  switch). Stop all activity immediately; revocation suspends all the agent's
  mandates within milliseconds.
- `429 RATE_LIMITED` — honor the `Retry-After` header (current per-IP limit:
  30 req/s, burst 20).

## Reading the docs

- Index of all pages: https://docs.regentprotocol.org/llms.txt
- Whole corpus in one file: https://docs.regentprotocol.org/llms-full.txt
- Any page as markdown: append `.md` to its URL
  (e.g. https://docs.regentprotocol.org/quickstart/three-steps.md), or request
  it with `Accept: text/markdown`.

Key references: [Quick Start](https://docs.regentprotocol.org/quickstart/three-steps.md) ·
[REST authentication](https://docs.regentprotocol.org/rest-api/authentication.md) ·
[Python SDK](https://docs.regentprotocol.org/sdk-python/guide/introduction.md) ·
[Cloud Gateway & MCP](https://docs.regentprotocol.org/gateway.md) ·
[Verifying on-chain](https://docs.regentprotocol.org/solana-programs/verification.md)