Recipes

Quick, self-contained solutions for specific tasks. Each recipe assumes you have an active agent with an SDK key. For initial setup, see Quickstart.

# Agent SDK key (for payment operations)
export CONTO_API_KEY="conto_agent_your_key_here"

# Org API key (for admin operations: managing agents, wallets, policies)
export CONTO_ORG_API_KEY="conto_your_org_key_here"

Agent Frameworks

Both skill flavors below rely on conto-check.sh, which in turn requires curl, jq, and python3 on PATH. curl and python3 ship with macOS and most Linux distros; install jq via your package manager. python3 powers the temporary browser callback used by conto-check.sh setup.

Install the OpenClaw Skill

npx clawhub install conto
bash skills/conto/conto-check.sh setup "my-openclaw-agent" "0xYourWalletAddress" EVM 42431

Use this when your OpenClaw agent already has wallet tools and you want Conto to become the policy gate. Review a payment that is waiting for the assigned human owner:

bash skills/conto/conto-check.sh pending-approvals
bash skills/conto/conto-check.sh approve-request APPROVAL_REQUEST_ID "Approved in OpenClaw"
# To deny instead:
bash skills/conto/conto-check.sh deny-request APPROVAL_REQUEST_ID "Recipient not recognized"

Use the listed approvalRequestId. The OpenClaw skill shows the payment details and requires the human user’s explicit decision before submitting it. A final managed-wallet approval returns the receipt directly. If the response contains nextAction.type: "EXECUTE_EXTERNALLY", execute those exact transfer fields with the OpenClaw wallet and confirm the returned hash:

bash skills/conto/conto-check.sh confirm PAYMENT_REQUEST_ID TX_HASH

Install the Hermes Skill

hermes skills install well-known:https://conto.finance/.well-known/skills/conto --force
bash ~/.hermes/skills/conto/conto-check.sh setup "my-hermes-agent" "0xYourWalletAddress" EVM 42431

Use this when you want Hermes-native skill installation with the same Conto policy and approval controls. Use --force only after reviewing the install scan.

Setup

Connect an Agent via API

First fetch a membership id for the human or service account that should own the agent:

curl https://conto.finance/api/organizations/me/members \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"

Then create the active agent with that members[].id:

curl -X POST https://conto.finance/api/agents \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "agentType": "CUSTOM",
    "ownerMembershipId": "cm0abc123...",
    "status": "ACTIVE"
  }'

Returns the agent ID. Use an organization API key (conto_...) for this call and include the intended owner’s ownerMembershipId.

Generate an SDK Key via API

curl -X POST https://conto.finance/api/agents/AGENT_ID/sdk-keys \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "expiresInDays": 90,
    "keyType": "standard"
  }'

Copy the key from the response. It’s only shown once.

Create a Managed Wallet

curl -X POST https://conto.finance/api/wallets \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Ops Wallet",
    "chainType": "EVM",
    "custodyMode": "MANAGED"
  }'

The response includes the wallet ID and onchain address. Use the wallet ID when linking it to an agent.

Link a Wallet to an Agent

curl -X POST https://conto.finance/api/agents/AGENT_ID/wallets \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "WALLET_ID",
    "delegationType": "LIMITED",
    "perTransactionLimit": 100,
    "dailyLimit": 500,
    "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
  }'

If you omit allowedDays, the wallet link is active every day. Send a narrower list, such as ["Mon", "Tue", "Wed", "Thu", "Fri"], only when you intentionally want weekend payments denied.

Check Agent Setup

Verify the agent is correctly configured with wallets and policies:

curl https://conto.finance/api/sdk/setup \
  -H "Authorization: Bearer $CONTO_API_KEY"

Payments

Request and Execute a Payment

Two calls: request (policy check) → execute (onchain transfer).

# Step 1: Request
REQUEST=$(curl -s -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "recipientAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "purpose": "Service payment"
  }')

echo $REQUEST

# Step 2: Execute (extract requestId from response)
curl -X POST https://conto.finance/api/sdk/payments/REQUEST_ID/execute \
  -H "Authorization: Bearer $CONTO_API_KEY"

Handle a Required Payment Action

Some merchant payments require the user to complete an additional step before settlement. In that case, the payment request returns HTTP 402 with status and code set to ACTION_REQUIRED and a single actionUrl.

curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25,
    "recipientAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "purpose": "Merchant checkout"
  }'

Open actionUrl for the user. After they finish, check the original requestId; do not submit a new payment or execute the original request until its status allows it.

Accept Agent Payments Through a Merchant Gate

Create a hosted gate for your merchant organization:

curl -X POST https://conto.finance/api/sdk/merchant-gates \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Commerce Checkout",
    "requireVerified": true,
    "requireKyc": true,
    "requireSanctionsClear": true,
    "allowedJurisdictions": ["US", "CA"],
    "settlementWalletId": "WALLET_ID",
    "settlementAsset": "USDC",
    "maxAmountPerPurchase": 250
  }'

Then let a buyer agent hit the public gate URL with the merchant:purchase scope:

curl -X POST https://conto.finance/api/merchant/GATE_ID/purchase \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25,
    "purpose": "Checkout order #1234",
    "category": "MERCHANT_GATE"
  }'

The gate returns a settlement result; a deny or approval result with stable reasonCodes, readable reasons, and nextAction; or ACTION_REQUIRED with an actionUrl. An idempotent retry while settlement is still in flight returns HTTP 202 with status: "PROCESSING" and can include the transaction explorer link when it is available.

Check Transaction Status

curl https://conto.finance/api/sdk/payments/REQUEST_ID \
  -H "Authorization: Bearer $CONTO_API_KEY"

Returns one of approved, declined, review_required, action_required, processing, completed, failed, or expired.

List Recent Transactions

curl https://conto.finance/api/sdk/transactions \
  -H "Authorization: Bearer $CONTO_API_KEY"

x402 and MPP Endpoint Calls

The pre-authorize → record → budget/services flows are documented once, with full request and response shapes, in the SDK reference:

x402 Payments: pre-authorize, record (including batch), budget, services
MPP Payments: pre-authorize, record settlements, budget, services

For both protocols, record endpoints use flat top-level settlement fields and optional batchItems for per-call detail. Do not send a top-level payments array. The policy recipes below show how to set the guardrails those endpoints enforce.

Approve and Confirm an External Wallet Payment

Use this flow when your agent holds its own keys and Conto should only authorize the spend.

# Step 1: Ask Conto for approval
APPROVAL=$(curl -s -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...",
    "purpose": "Vendor payout",
    "chainId": 42431
  }')

echo $APPROVAL

# Step 2: Agent executes the transfer with its own wallet tools
# Step 3: Confirm the onchain transfer back to Conto
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": "APPROVAL_TOKEN"
  }'

Policies

Limit Agent to $50/Day

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Cap: $50",
    "policyType": "SPEND_LIMIT",
    "rules": [
      {
        "ruleType": "DAILY_LIMIT",
        "operator": "LTE",
        "value": "50",
        "action": "ALLOW"
      }
    ]
  }'

Then assign to agent:

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" }'

Require Approval Above $100

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Approval Above $100",
    "policyType": "APPROVAL_THRESHOLD",
    "rules": [
      {
        "ruleType": "REQUIRE_APPROVAL_ABOVE",
        "operator": "GREATER_THAN",
        "value": "100",
        "action": "REQUIRE_APPROVAL"
      }
    ]
  }'

Block Payments Outside Business Hours

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours Only",
    "policyType": "TIME_WINDOW",
    "rules": [
      {
        "ruleType": "TIME_WINDOW",
        "operator": "BETWEEN",
        "value": "{\"start\": \"09:00\", \"end\": \"17:00\"}",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAY_OF_WEEK",
        "operator": "IN_LIST",
        "value": "[\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\"]",
        "action": "ALLOW"
      }
    ]
  }'

Allowlist Specific Recipients

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Approved Vendors Only",
    "policyType": "COUNTERPARTY",
    "rules": [
      {
        "ruleType": "ALLOWED_COUNTERPARTIES",
        "operator": "IN_LIST",
        "value": "[\"0x1234567890abcdef1234567890abcdef12345678\", \"0xabcdef1234567890abcdef1234567890abcdef12\"]",
        "action": "ALLOW"
      }
    ]
  }'

Cap x402 API Spending

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "x402 Guardrails",
    "policyType": "COMPOSITE",
    "rules": [
      {
        "ruleType": "X402_MAX_PER_REQUEST",
        "operator": "LTE",
        "value": "0.10",
        "action": "ALLOW"
      },
      {
        "ruleType": "X402_MAX_PER_SERVICE",
        "operator": "LTE",
        "value": "{\"maxAmount\": 25, \"period\": \"DAILY\"}",
        "action": "ALLOW"
      }
    ]
  }'

Restrict to Allowed x402 Services

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "x402 Service Allowlist",
    "policyType": "COMPOSITE",
    "rules": [
      {
        "ruleType": "X402_ALLOWED_SERVICES",
        "operator": "IN_LIST",
        "value": "[\"api.example.com\", \"data.provider.io\"]",
        "action": "ALLOW"
      }
    ]
  }'

Cap MPP Session Deposits

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MPP Session Guardrails",
    "policyType": "COMPOSITE",
    "rules": [
      {
        "ruleType": "MPP_MAX_SESSION_DEPOSIT",
        "operator": "LTE",
        "value": "25",
        "action": "ALLOW"
      },
      {
        "ruleType": "MPP_MAX_PER_REQUEST",
        "operator": "LTE",
        "value": "1.00",
        "action": "ALLOW"
      },
      {
        "ruleType": "MPP_MAX_CONCURRENT_SESSIONS",
        "operator": "LTE",
        "value": "3",
        "action": "ALLOW"
      }
    ]
  }'

Restrict MPP to Allowed Services

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MPP Service Allowlist",
    "policyType": "COMPOSITE",
    "rules": [
      {
        "ruleType": "MPP_ALLOWED_SERVICES",
        "operator": "IN_LIST",
        "value": "[\"api.service.com\", \"streaming.provider.io\"]",
        "action": "ALLOW"
      }
    ]
  }'

Approvals & Trust

Look Up Trust for a Counterparty Address

curl https://conto.finance/api/sdk/network/trust/0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 \
  -H "Authorization: Bearer $CONTO_API_KEY"

Requires the network:read scope. Returns normalized trust information, a relationship summary, aggregate transaction history, and an active risk-signal count.

Require Approval for Large Payments and Use Slack for Review

The fastest production pattern is:

Create an approval threshold rule:

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Approval Above $500",
    "policyType": "APPROVAL_THRESHOLD",
    "rules": [
      {
        "ruleType": "REQUIRE_APPROVAL_ABOVE",
        "operator": "GREATER_THAN",
        "value": "500",
        "action": "REQUIRE_APPROVAL"
      }
    ]
  }'

Configure a Slack approval channel:

See /guides/external-approvals for the full Slack setup and approval action flow.

Monitoring

Get Agent Spending Summary

curl "https://conto.finance/api/sdk/analytics?period=month" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Get Wallet Balance

curl https://conto.finance/api/sdk/wallets \
  -H "Authorization: Bearer $CONTO_API_KEY"

Returns all linked wallets with current balances.

List Active Alerts

curl https://conto.finance/api/alerts \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"

TypeScript SDK Equivalents

The recipes above use curl. Here are the payment operations in TypeScript using the SDK:

import { Conto } from '@conto_finance/sdk';
const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });

// Request + execute payment
const req = await conto.payments.request({
  amount: 10,
  recipientAddress: '0x...',
  purpose: 'Service payment',
});
if (req.status === 'APPROVED') {
  const tx = await conto.payments.execute(req.requestId);
  console.log(tx.receipt?.explorerUrl);
}

// Check status
const status = await conto.payments.status(req.requestId);

// Single-call payment (request + execute)
const result = await conto.payments.pay({
  amount: 50,
  recipientAddress: '0x...',
  purpose: 'API credits',
});
console.log(result.receipt?.txHash);

The Conto class provides conto.payments for agent payment operations. For admin operations (agents, wallets, policies) use ContoAdmin, see the Admin SDK. For x402 and MPP, use the REST endpoints in the x402 and MPP SDK references; for transaction listing and wallet queries, use the curl recipes above.

Choose Integration

SDK vs Agent Skills vs x402 vs MPP

Quickstart

Full setup walkthrough

x402 Payments

Pay for APIs with x402

MPP Sessions

Session-based micropayments

Approval Workflows

Add review and escalation controls

Trust Scoring

Use counterparty trust as a control surface

​Recipes

​Agent Frameworks

​Install the OpenClaw Skill

​Install the Hermes Skill

​Setup

​Connect an Agent via API

​Generate an SDK Key via API

​Create a Managed Wallet

​Link a Wallet to an Agent

​Check Agent Setup

​Payments

​Request and Execute a Payment

​Handle a Required Payment Action

​Accept Agent Payments Through a Merchant Gate

​Check Transaction Status

​List Recent Transactions

​x402 and MPP Endpoint Calls

​Approve and Confirm an External Wallet Payment

​Policies

​Limit Agent to $50/Day

​Require Approval Above $100

​Block Payments Outside Business Hours

​Allowlist Specific Recipients

​Cap x402 API Spending

​Restrict to Allowed x402 Services

​Cap MPP Session Deposits

​Restrict MPP to Allowed Services

​Approvals & Trust

​Look Up Trust for a Counterparty Address

​Require Approval for Large Payments and Use Slack for Review

​Monitoring

​Get Agent Spending Summary

​Get Wallet Balance

​List Active Alerts

​TypeScript SDK Equivalents

​Related

Choose Integration

Quickstart

x402 Payments

MPP Sessions

Approval Workflows

Trust Scoring

Recipes

Agent Frameworks

Install the OpenClaw Skill

Install the Hermes Skill

Setup

Connect an Agent via API

Generate an SDK Key via API

Create a Managed Wallet

Link a Wallet to an Agent

Check Agent Setup

Payments

Request and Execute a Payment

Handle a Required Payment Action

Accept Agent Payments Through a Merchant Gate

Check Transaction Status

List Recent Transactions

x402 and MPP Endpoint Calls

Approve and Confirm an External Wallet Payment

Policies

Limit Agent to $50/Day

Require Approval Above $100

Block Payments Outside Business Hours

Allowlist Specific Recipients

Cap x402 API Spending

Restrict to Allowed x402 Services

Cap MPP Session Deposits

Restrict MPP to Allowed Services

Approvals & Trust

Look Up Trust for a Counterparty Address

Require Approval for Large Payments and Use Slack for Review

Monitoring

Get Agent Spending Summary

Get Wallet Balance

List Active Alerts

TypeScript SDK Equivalents

Related