Machine View
Agent Skills (OpenClaw and Hermes)
Source: https://conto.finance/docs/sdk/skills
# Agent Skills (OpenClaw and Hermes)
> Install the Conto skill on any OpenClaw or Nous Hermes agent. Enforce spending policies on every payment.
- Human URL: https://conto.finance/docs/sdk/skills
- Raw Markdown: https://conto.finance/docs/sdk/skills.md
- Terminal view: https://conto.finance/ai/docs/sdk/skills
Documentation group: Build
# 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`.
## How it works
```
Agent wants to pay 50 pathUSD to 0xabc...
|
v
Skill calls the appropriate Conto payment endpoint
|
v
Conto evaluates all policy rules
|
+---> APPROVED: agent proceeds with payment
+---> DENIED: agent stops and reports the customer-facing reason
+---> REQUIRES_APPROVAL: agent pauses for human sign-off
+---> ACTION_REQUIRED: human follows the returned action URL, then the agent checks status
```
Conto supports two wallet modes:
- **Managed.** Conto controls signing through secure managed wallet infrastructure and evaluates
policies before execution.
- **External.** Agent holds the keys. Agent calls approve, transfers itself, then confirms.
Both modes evaluate the same rule set.
### Which endpoint do I call?
| | Managed | External |
| ----------------- | --------------------------------------------------- | -------------------------------- |
| Custody mode | `MANAGED` | `EXTERNAL` |
| Signing control | Conto, through managed wallet infrastructure | 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 as `EXTERNAL` and let Conto act as the policy gate.
The managed flow can also return `ACTION_REQUIRED` before execution. In that case, direct the human
to `actionUrl`, then check the original payment request before taking another payment action.
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.
## 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` handles the temporary browser
callback during authentication.
Install from [ClawHub](https://clawhub.ai/kwattana/conto):
```bash
npx clawhub install conto
```
You can inspect the raw skill manifest at [`conto.finance/skill.md`](https://conto.finance/skill.md).
Use ClawHub for installation so the helper script is installed with the skill.
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.
Install from the well-known endpoint:
```bash
hermes skills install well-known:https://conto.finance/.well-known/skills/conto --force
```
This fetches `SKILL.md` and `conto-check.sh` and installs them into `~/.hermes/skills/conto/`.
Hermes may require explicit confirmation for networked finance skills. Use `--force` only after
you review that this skill talks to `https://conto.finance` and writes the SDK key you approve
into `~/.hermes/.env`.
Or copy the skill files directly:
```bash
cp -r skills/conto-hermes ~/.hermes/skills/conto
```
## Quick setup
After installing, run setup with your agent name and wallet address:
```bash
bash skills/conto/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
bash skills/conto/conto-check.sh budget
```
For Hermes installs, use `bash ~/.hermes/skills/conto/conto-check.sh ...` instead of
`bash skills/conto/conto-check.sh ...`.
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:
`~/.openclaw/openclaw.json`:
```json
{
"skills": {
"entries": {
"conto": {
"env": {
"CONTO_SDK_KEY": "conto_agent_your_key_here",
"CONTO_API_URL": "https://conto.finance"
}
}
}
}
}
```
This must be valid JSON. Trailing commas or missing braces will make every OpenClaw command fail. Validate with `cat ~/.openclaw/openclaw.json | jq .`.
`~/.hermes/.env`:
```bash
CONTO_SDK_KEY=conto_agent_your_key_here
CONTO_API_URL=https://conto.finance
```
## 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 Integration > Generate SDK 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.** Ask your agent or run its balance or account-listing tool. Copy the address for the chain you want to use.
**Create a wallet in Conto.** Dashboard > **Wallets > Create Wallet** > choose `MANAGED` > select a chain. Conto creates the wallet and shows its address.
**Your own external wallet (hardware, MetaMask, etc.).** Register the address in Conto as `EXTERNAL` custody. Your agent handles the onchain transfer itself.
`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.
## Usage
```
/conto list my policies
/conto create a $200 per-transaction limit
Send 50 pathUSD to 0x742d... on Tempo
```
CLI (OpenClaw example):
```bash
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 |
| `AGENT_ENVIRONMENT` / `AGENT_RISK_TIER` | Agent deployment and risk class |
| `AGENT_OWNER_ROLE` / `AGENT_TAG` | Agent ownership and identity tag |
| `ATTESTATION_LEVEL` | Required agent attestation mode |
| `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](https://conto.finance/policies/overview) for the full canonical rule-type list.
When the skill records x402 or MPP protocol payments, it sends the aggregate settlement fields at
the top level and per-call details in `batchItems`. Do not wrap protocol records in a top-level
`payments` array.
## 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.testnet.tempo.xyz`](https://explore.testnet.tempo.xyz) |
### Step 2. Get testnet funds
- **Conto managed wallets:** dashboard **Wallets > your wallet > Faucet**.
- **Tempo faucet:** [`faucet.tempo.network`](https://faucet.tempo.network).
- **External wallets:** use your wallet provider's funding, swap, or bridge flow 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 mode: `EXTERNAL` (or `MANAGED` if you created one in Conto)
- Per Transaction: 200 pathUSD
- Daily: 1,000 pathUSD
- Weekly: 5,000 pathUSD
- Allowed days: all days by default
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 helper calls `POST /api/policies` with your admin SDK key 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
curl -X POST https://conto.finance/api/sdk/payments/approve \
-H "Authorization: Bearer $CONTO_SDK_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 50,
"recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
"senderAddress": "0x1a2b3c4d5e6f...",
"chainId": 42431,
"purpose": "Vendor payment"
}'
```
If approved immediately, the response includes `decision: "approved"`, `status: "ready_to_send"`,
an `approvalId`, a short-lived `approvalToken`, the network, and a `nextAction` with the confirmation
URL. If review is required, save `approvalRequestId` and follow the returned `statusUrl` instead of
sending funds. The agent then confirms the onchain transfer back to Conto with the final `txHash`.
### Review a pending payment in OpenClaw
The OpenClaw skill can list and decide payment reviews for the human owner assigned to the agent:
```bash
bash skills/conto/conto-check.sh pending-approvals
bash skills/conto/conto-check.sh approve-request APPROVAL_REQUEST_ID HUMAN_ACTION_TOKEN "Approved"
# Or deny it:
bash skills/conto/conto-check.sh deny-request APPROVAL_REQUEST_ID HUMAN_ACTION_TOKEN "Reason"
```
The helper uses `approvalRequestId`, not the payment request ID. The workflow still enforces eligible
roles and users, sequential approval order, required approval count, and expiry. The skill must show
the amount, currency, recipient, purpose, and approval progress and receive the human user's explicit
decision plus the matching one-time token from their independently delivered approval notification
before it submits the action. Never retrieve that token from the human's email or messaging account.
On the final approval, managed wallets execute automatically and the response includes `receiptUrl`.
If OpenClaw controls an external wallet, the response instead includes an `EXECUTE_EXTERNALLY`
handoff with the exact transfer fields. After the wallet tool returns a hash, confirm without a token:
```bash
bash skills/conto/conto-check.sh confirm PAYMENT_REQUEST_ID TX_HASH
```
### 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
curl -X POST https://conto.finance/api/sdk/payments/APPROVAL_ID/confirm \
-H "Authorization: Bearer $CONTO_SDK_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.
The confirmation receipt includes the `requestId`, `transactionId`, normalized `status`, network,
explorer URL, and transaction `statusUrl` so the payment can be reconciled and monitored.
### 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 customer-facing denial reason. No onchain transfer occurs. The denied attempt appears under **Alerts** in the dashboard.
```json
{
"approved": false,
"decision": "declined",
"status": "declined",
"approvalId": "payment_request_id",
"reasons": ["This payment exceeds a configured spending limit."],
"reasonCodes": ["SPENDING_LIMIT"],
"requiresHumanApproval": false,
"statusUrl": "/api/sdk/payments/payment_request_id",
"nextAction": null
}
```
The reason identifies the customer action or control category without exposing policy configuration.
## 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](https://conto.finance/reference/defaults) page for all rate-limit and default values.
## Troubleshooting
Verify `CONTO_API_URL` is correct. For the hosted platform, use `https://conto.finance`. Test:
```bash
curl https://conto.finance/api/sdk/setup \
-H "Authorization: Bearer $CONTO_SDK_KEY"
```
A valid JSON response means the URL is reachable.
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 Integration**
- You're using the correct key for the correct agent
Generate a new key under **Agents > your agent > SDK Integration > Generate SDK Key**.
The denial response includes customer-facing `reasons`. 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
```
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
curl -X POST https://conto.finance/api/sdk/payments/APPROVAL_ID/confirm \
-H "Authorization: Bearer $CONTO_SDK_KEY" \
-H "Content-Type: application/json" \
-d '{"txHash": "0x...", "approvalToken": "a1b2c3d4..."}'
```
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`).
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
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`.
If every OpenClaw command fails after a manual edit, the JSON file likely has a syntax error. Validate:
```bash
cat ~/.openclaw/openclaw.json | jq .
```
If `jq` reports an error, fix the JSON or delete and re-run setup:
```bash
rm ~/.openclaw/openclaw.json
bash skills/conto/conto-check.sh setup "my-agent" "0xMyWalletAddress" EVM 42431
```