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

# Agent Skills (OpenClaw and Hermes)

> Install the Conto skill on any OpenClaw or Nous Hermes agent. Enforce spending policies on every payment.

# Agent Skills

The Conto skill adds spending-policy enforcement to any AI agent built on [OpenClaw](https://github.com/openclaw/openclaw) or [Nous Hermes](https://hermes-agent.nousresearch.com/). It checks every payment against 40+ policy rule types before money leaves the wallet.

Both frameworks use the same wrapper script (`conto-check.sh`) and the same Conto REST API. Only the install command and the config file location differ.

<Info>
  In the examples below, `pathUSD` refers to Tempo Testnet. For production wallets on Tempo Mainnet,
  use `USDC.e`.
</Info>

## How it works

```
Agent wants to pay 50 pathUSD to 0xabc...
    |
    v
Skill calls POST /api/sdk/payments/approve
    |
    v
Conto evaluates all policy rules
    |
    +---> APPROVED: agent proceeds with payment
    +---> DENIED: agent stops, reports violations
    +---> REQUIRES_APPROVAL: agent pauses for human sign-off
    +---> VERIFICATION_REQUIRED: human completes AgentScore identity step-up, then Conto resumes
```

Conto supports two wallet modes:

* **Integrated (PRIVY/SPONGE).** Your wallet provider holds the keys. Conto evaluates policies and orchestrates execution through the provider.
* **External.** Agent holds the keys. Agent calls approve, transfers itself, then confirms.

Both modes evaluate the same rule set.

### Which endpoint do I call?

|                   | Integrated (PRIVY/SPONGE)                           | External                         |
| ----------------- | --------------------------------------------------- | -------------------------------- |
| Custody type      | `PRIVY` or `SPONGE`                                 | `EXTERNAL`                       |
| Who holds keys    | Wallet provider                                     | Your agent                       |
| Endpoint          | `POST /api/sdk/payments/request`                    | `POST /api/sdk/payments/approve` |
| Calls per payment | 1 (with `autoExecute: true` and `payments:execute`) | 3 (approve, transfer, confirm)   |
| Approval expiry   | 5 minutes                                           | 10 minutes                       |
| `chainId`         | Resolved from wallet                                | Required in request body         |

Most skill users register an existing wallet (e.g. through an MCP server like Sponge) as `EXTERNAL` and let Conto act as the policy gate.

If you enable AgentScore-backed merchant gating, the integrated flow can also return
`VERIFICATION_REQUIRED` before execution. In that case the human verifies identity through the
provided URL, Conto re-runs policy evaluation with the merchant compliance result, and then the
payment proceeds or fails normally.

<Info>
  The default **Standard SDK key** preset includes the payment scopes these flows need:
  `payments:execute`, `payments:approve`, and `payments:confirm`. Admin SDK keys are only required
  for the policy management commands covered later in this guide.
</Info>

## Install

Requirements: `conto-check.sh` uses `curl`, `jq`, and `python3`. Install `jq` via your package manager if missing (`brew install jq`, `apt install jq`). `python3` runs a short-lived localhost callback server during browser auth.

<Tabs>
  <Tab title="OpenClaw">
    Install from [ClawHub](https://clawhub.ai/kwattana/conto):

    ```bash theme={null}
    npx clawhub install conto
    ```

    Or add the skill directly from the manifest: [`conto.finance/skill.md`](https://conto.finance/skill.md).

    <Warning>
      Do not run `npm install @conto_finance/sdk`. The OpenClaw skill uses `conto-check.sh` (installed by ClawHub) to call the Conto REST API directly. The `@conto_finance/sdk` npm package is a separate TypeScript SDK and is not needed here.
    </Warning>
  </Tab>

  <Tab title="Nous Hermes">
    Install from the well-known endpoint:

    ```bash theme={null}
    hermes skills install well-known:https://conto.finance/.well-known/skills/conto
    ```

    This fetches `SKILL.md` and `conto-check.sh` and installs them into `~/.hermes/skills/conto/`.

    Or copy the skill files directly:

    ```bash theme={null}
    cp -r skills/conto-hermes ~/.hermes/skills/conto
    ```
  </Tab>
</Tabs>

## Quick setup

After installing, run setup with your agent name and wallet address:

```bash theme={null}
conto-check.sh setup "my-agent" "0xYourWalletAddress" EVM 42431
```

This opens your browser for Conto login. After you approve, the agent is automatically provisioned with:

* An agent record linked to your organization
* Your wallet registered as `EXTERNAL` custody
* Default spend limits ($100/tx, $500/day)
* An SDK key written to the framework's config file (see below)

| Argument         | Default  | Description                                                    |
| ---------------- | -------- | -------------------------------------------------------------- |
| `agent_name`     | required | Name for your agent                                            |
| `wallet_address` | required | Your wallet address (`0x...` for EVM, base58 for Solana)       |
| `chain_type`     | `EVM`    | `EVM` or `SOLANA`                                              |
| `chain_id`       | `42431`  | Common: `8453` (Base), `42431` (Tempo Testnet), `1` (Ethereum) |

Verify it works:

```bash theme={null}
conto-check.sh budget
```

You can adjust spend limits, add policies, and manage the agent in the [Conto dashboard](https://conto.finance).

## Config file locations

The skill writes the SDK key to a framework-specific path:

<Tabs>
  <Tab title="OpenClaw">
    `~/.openclaw/openclaw.json`:

    ```json theme={null}
    {
      "skills": {
        "entries": {
          "conto": {
            "env": {
              "CONTO_API_KEY": "conto_agent_your_key_here",
              "CONTO_API_URL": "https://conto.finance"
            }
          }
        }
      }
    }
    ```

    <Warning>
      This must be valid JSON. Trailing commas or missing braces will make every OpenClaw command fail. Validate with `cat ~/.openclaw/openclaw.json | jq .`.
    </Warning>
  </Tab>

  <Tab title="Nous Hermes">
    `~/.hermes/.env`:

    ```bash theme={null}
    CONTO_API_KEY=conto_agent_your_key_here
    CONTO_API_URL=https://conto.finance
    ```
  </Tab>
</Tabs>

## Manual setup

If browser-based setup doesn't work, configure manually:

1. **Connect your agent in Conto.** Sign in to the [Conto dashboard](https://conto.finance) and create the agent record.
2. **Link your wallet.** Go to **Agents > your agent > Wallets > Link Wallet**. Enter the address and chain. Set initial spending limits.
3. **Generate an SDK key.** Go to **Agents > your agent > SDK Keys > Generate New Key**. Pick
   **Standard** for payment flows; the preset includes the request, execute, approve, and confirm
   scopes this skill uses. Pick **Admin** only if you also want the skill to manage policies,
   agents, or wallets.
4. **Save the key** to the config path for your framework (above).

## Finding your wallet address

How you obtain a wallet address depends on your setup.

**Existing MCP wallet (Sponge, AgentCash).** Ask your agent or run the `get_balance` / `list_accounts` tool. Copy the address for the chain you want to use.

**Create a wallet in Conto.** Dashboard > **Wallets > Create Wallet** > pick `PRIVY` or `SPONGE` custody > select chain > **Provision**. Conto creates the wallet onchain and shows the address.

**Your own external wallet (hardware, MetaMask, etc.).** Register the address in Conto as `EXTERNAL` custody. Your agent handles the onchain transfer itself.

<Warning>
  `EXTERNAL` custody keeps full key control in your wallet stack. Conto can approve, deny, record,
  and alert on payments routed through Conto, but it cannot cryptographically block a direct
  transfer signed outside Conto.
</Warning>

## Usage

```
/conto list my policies
/conto create a $200 per-transaction limit
Send 50 pathUSD to 0x742d... on Tempo
```

CLI (OpenClaw example):

```bash theme={null}
openclaw agent --agent main -m "Send 50 pathUSD to 0x742d... on Tempo"
```

## Standard vs Admin SDK keys

| Capability                       | Standard | Admin |
| -------------------------------- | -------- | ----- |
| Request policy evaluation        | Yes      | Yes   |
| Execute approved payments        | Yes      | Yes   |
| Approve / confirm payments       | Yes      | Yes   |
| Pre-authorize x402 calls         | Yes      | Yes   |
| Create merchant acceptance gates | No       | Yes   |
| Read policies and transactions   | Yes      | Yes   |
| Create/update/delete policies    | No       | Yes   |
| Manage agents and wallets        | No       | Yes   |

With an admin key, manage policies through natural language:

```
/conto create a policy that limits each transaction to 200 pathUSD
/conto create a policy that only allows API_PROVIDER and CLOUD categories
/conto block address 0xbad... from receiving payments
/conto create a policy that requires approval for payments over 500 pathUSD
/conto delete the blocklist policy
```

## Supported policy types

| Type                                                | What it controls                 |
| --------------------------------------------------- | -------------------------------- |
| `MAX_AMOUNT`                                        | Per-transaction cap              |
| `DAILY_LIMIT` / `WEEKLY_LIMIT` / `MONTHLY_LIMIT`    | Cumulative spend caps            |
| `ALLOWED_CATEGORIES` / `BLOCKED_CATEGORIES`         | Category allowlist/blocklist     |
| `ALLOWED_COUNTERPARTIES` / `BLOCKED_COUNTERPARTIES` | Address allowlist/blocklist      |
| `TIME_WINDOW` / `DAY_OF_WEEK`                       | Business hours, allowed days     |
| `BLACKOUT_PERIOD`                                   | Maintenance windows              |
| `VELOCITY_LIMIT`                                    | Transaction rate limiting        |
| `REQUIRE_APPROVAL_ABOVE`                            | Human approval threshold         |
| `GEOGRAPHIC_RESTRICTION`                            | Country / OFAC restrictions      |
| `CONTRACT_ALLOWLIST`                                | DeFi contract restrictions       |
| `X402_PRICE_CEILING`                                | Max per x402 API call            |
| `X402_ALLOWED_SERVICES` / `X402_BLOCKED_SERVICES`   | x402 service allowlist/blocklist |
| `X402_MAX_PER_SERVICE`                              | Per-service daily cap            |

See [Policy overview](/policies/overview) for the full canonical rule-type list.

## End-to-end example: pay a vendor on Tempo Testnet

This walks the full external-wallet flow: approve, transfer onchain, confirm back to Conto.

### Prerequisites

* Conto account with the agent connected
* Conto skill installed in OpenClaw or Hermes
* SDK key configured (see [Config file locations](#config-file-locations))
* A wallet address (see [Finding your wallet address](#finding-your-wallet-address))

### Step 1. Tempo Testnet details

| Detail   | Value                                                              |
| -------- | ------------------------------------------------------------------ |
| Network  | Tempo Testnet                                                      |
| Chain ID | `42431`                                                            |
| Currency | `pathUSD` (TIP-20 stablecoin)                                      |
| Gas      | Paid in `pathUSD` (no separate gas token)                          |
| Explorer | [`explore.moderato.tempo.xyz`](https://explore.moderato.tempo.xyz) |

### Step 2. Get testnet funds

* **Conto Privy wallets:** dashboard **Wallets > your wallet > Faucet**.
* **Tempo faucet:** [`faucet.tempo.network`](https://faucet.tempo.network).
* **Sponge MCP wallets:** ask your agent for the balance and swap or bridge if needed.

You need enough `pathUSD` to cover the test payment plus a small amount for fees.

### Step 3. Register the wallet in Conto

Dashboard > **Agents > your agent > Wallets > Link Wallet**. Set:

* Chain: Tempo Testnet (`42431`)
* Custody type: `EXTERNAL` (or `PRIVY` if you created one in Conto)
* Per Transaction: 200 pathUSD
* Daily: 1,000 pathUSD
* Weekly: 5,000 pathUSD

Wallet-level limits act as a safety net on top of any policy you assign.

### Step 4. Create a policy

```
/conto create a policy that limits each transaction to 200 pathUSD
```

The skill calls `POST /api/sdk/policies` and returns the policy ID. Verify:

```
/conto list my policies
```

### Step 5. Request a payment

```
Send 50 pathUSD to 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 on Tempo
```

Behind the scenes the skill calls:

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/approve \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "senderAddress": "0x1a2b3c4d5e6f...",
    "chainId": 42431,
    "purpose": "Vendor payment"
  }'
```

If approved immediately, the response includes an `approvalId` and `approvalToken`. If policy
requires manual approval and a workflow matches, the response includes `approvalRequestId` instead.
Once that workflow approves the payment, the agent confirms the onchain transfer back to Conto with
the final `txHash`.

### Step 6. Transfer onchain

The agent transfers `pathUSD` itself using its own keys. The skill handles this for you.

### Step 7. Confirm back to Conto

After the onchain transfer succeeds:

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/APPROVAL_ID/confirm \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0xabc123...",
    "approvalToken": "a1b2c3d4..."
  }'
```

Conto records the payment, updates spend counters, and the transaction appears in the dashboard.

### Step 8. Verify

```
/conto show my recent transactions
```

Or check **Transactions** in the dashboard for the explorer link.

### What happens when a policy blocks the payment?

```
Send 300 pathUSD to 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 on Tempo
```

The skill returns a denial with the specific violation. No onchain transfer occurs. The denied attempt appears under **Alerts** in the dashboard.

```json theme={null}
{
  "approved": false,
  "reasons": ["Amount 300 exceeds maximum of 200 per transaction"],
  "violations": [
    {
      "type": "PER_TX_LIMIT",
      "limit": 200,
      "current": 300,
      "message": "Amount 300 exceeds maximum of 200 per transaction"
    }
  ],
  "requiresHumanApproval": false
}
```

Common violation types: `PER_TX_LIMIT`, `DAILY_LIMIT`, `WEEKLY_LIMIT`, `MONTHLY_LIMIT`, `BLOCKED_COUNTERPARTY`, `TIME_WINDOW`, `CATEGORY_RESTRICTION`, `VELOCITY_LIMIT`. See [Advanced policies](/policies/advanced) for the full list.

## Rate limits

| Endpoint type                                                      | Limit                      |
| ------------------------------------------------------------------ | -------------------------- |
| Payment endpoints (`/approve`, `/request`, `/execute`, `/confirm`) | 60 requests/min per agent  |
| Read endpoints (`/wallets`, `/policies`, `/transactions`, etc.)    | 120 requests/min per agent |

On `429`, the API returns a `Retry-After` header. The skill retries automatically.

See the [Defaults](/reference/defaults) page for all rate-limit and default values.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Skill can't reach Conto (connection refused / timeout)">
    Verify `CONTO_API_URL` is correct. For the hosted platform, use `https://conto.finance`. For local dev, `http://localhost:3006`. Test:

    ```bash theme={null}
    curl https://conto.finance/api/sdk/setup \
      -H "Authorization: Bearer $CONTO_API_KEY"
    ```

    A valid JSON response means the URL is reachable.
  </Accordion>

  <Accordion title="'Invalid or expired SDK key'">
    SDK keys are scoped to a single agent. Check that:

    * The key starts with `conto_agent_` (not `conto_`)
    * The key has not been revoked in **Agents > SDK Keys**
    * You're using the correct key for the correct agent

    Generate a new key under **Agents > your agent > SDK Keys > Generate New Key**.
  </Accordion>

  <Accordion title="Payment denied unexpectedly">
    The denial response includes a `violations` array listing every rule that failed. Common causes:

    * Spend limit exceeded. Check daily/weekly/monthly counters in **Agents > Spend Tracking**.
    * Counterparty not on allowlist. If you have an `ALLOWED_COUNTERPARTIES` policy, the recipient must be listed.
    * Outside time window. `TIME_WINDOW` and `DAY_OF_WEEK` policy rules use the server's local time; wallet-level time windows support explicit IANA timezones.
    * Category mismatch. If `ALLOWED_CATEGORIES` is set and no `category` is provided, the allow rule denies because the category cannot be verified. `BLOCKED_CATEGORIES` skips when no category is present.

    Dry-run check without attempting a real payment:

    ```
    /conto check if a 50 pathUSD payment to 0x742d... is allowed
    ```
  </Accordion>

  <Accordion title="Payment approved but no onchain transfer (external wallet)">
    In external wallet mode, Conto only enforces policy. The agent must transfer funds itself. If `/approve` succeeds but no transfer happens:

    * Check the agent has enough `pathUSD` in its wallet.
    * Check the agent logs for transfer errors.
    * Ensure the wallet address in Conto matches the agent's actual wallet.

    If the transfer succeeded but Conto doesn't show it, the `/confirm` call may have failed. Retry:

    ```bash theme={null}
    curl -X POST https://conto.finance/api/sdk/payments/APPROVAL_ID/confirm \
      -H "Authorization: Bearer $CONTO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"txHash": "0x...", "approvalToken": "a1b2c3d4..."}'
    ```
  </Accordion>

  <Accordion title="Admin commands fail with 'insufficient permissions'">
    Policy management requires an Admin SDK key. The default Standard preset covers the payment
    lifecycle (`payments:request`, `payments:execute`, `payments:approve`, `payments:confirm`) and
    reads, but not management scopes like `policies:write`. Check the key type in **Agents > SDK
    Keys** (scope column shows `standard` or `admin`).
  </Accordion>

  <Accordion title="Policies not evaluating (all payments approved)">
    Policies must be assigned to the agent. Creating a policy alone doesn't activate it. Assign via the dashboard (**Policies > Assign to Agent**) or via the API:

    ```bash theme={null}
    curl -X POST https://conto.finance/api/agents/AGENT_ID/policies \
      -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"policyId": "POLICY_ID"}'
    ```

    Verify the policy status is `ACTIVE`.
  </Accordion>

  <Accordion title="OpenClaw errors after editing openclaw.json">
    If every OpenClaw command fails after a manual edit, the JSON file likely has a syntax error. Validate:

    ```bash theme={null}
    cat ~/.openclaw/openclaw.json | jq .
    ```

    If `jq` reports an error, fix the JSON or delete and re-run setup:

    ```bash theme={null}
    rm ~/.openclaw/openclaw.json
    conto-check.sh setup "my-agent" "0xMyWalletAddress" EVM 42431
    ```
  </Accordion>
</AccordionGroup>