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 localhost OAuth 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.

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. Current Hermes releases require --force for this networked finance skill after you review 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": "mem_abc123...",
    "status": "ACTIVE"
  }'

Returns the agent ID. Use an org-level API key (conto_...) for this call. Browser-session requests can default to the current member, but org API key calls should include ownerMembershipId so ownership and policy repair flows remain deterministic.

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.

Provision a Sponge Wallet

Sponge custody uses the @paysponge/sdk under the hood. Set SPONGE_API_KEY (and SPONGE_MASTER_KEY for fleet management) in your environment.

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",
    "custodyType": "SPONGE"
  }'

Then provision it to generate an onchain address:

curl -X POST https://conto.finance/api/wallets/WALLET_ID/provision \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"

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"

Pay an AgentScore-Gated Merchant

If the merchant is AgentScore-native, include the merchant compliance policy in the request. Conto will return VERIFICATION_REQUIRED with a verification URL when the operator identity needs a step-up before settlement.

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",
    "autoExecute": true,
    "agentScorePolicy": {
      "requireVerified": true,
      "requireKyc": true,
      "requireSanctionsClear": true,
      "allowedJurisdictions": ["US"]
    }
  }'

If the response status is VERIFICATION_REQUIRED, direct the human to verification.verifyUrl. Once the session completes, Conto re-runs policy evaluation and auto-executes if the original call used autoExecute: true.

Accept Agent Payments Through a Merchant Gate

Create a hosted gate for your merchant org:

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 either an executed payment, a normal Conto deny/approval result, or a 403 with AgentScore verify_url / poll_url / poll_secret fields when identity verification is still required.

Check Transaction Status

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

Returns PENDING, CONFIRMING, CONFIRMED, FAILED, or REJECTED.

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 global trust information, relationship-specific trust data, transaction history, and any network flags.

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

​Provision a Sponge Wallet

​Link a Wallet to an Agent

​Check Agent Setup

​Payments

​Request and Execute a Payment

​Pay an AgentScore-Gated Merchant

​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

Provision a Sponge Wallet

Link a Wallet to an Agent

Check Agent Setup

Payments

Request and Execute a Payment

Pay an AgentScore-Gated Merchant

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