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

Setup

Connect an Agent via API

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",
    "status": "ACTIVE"
  }'

Returns the agent ID. Use an org-level API key (conto_...) for this call.

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

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": {
      "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",
    "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/status \
  -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"

Pre-Authorize an x402 Payment

curl -X POST https://conto.finance/api/sdk/x402/pre-authorize \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xFacilitatorAddress",
    "resourceUrl": "https://api.example.com/data"
  }'

Returns "authorized": true with wallet details, or "authorized": false with violation reasons.

Record an x402 Transaction

After the x402 payment executes onchain:

curl -X POST https://conto.finance/api/sdk/x402/record \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xFacilitatorAddress",
    "txHash": "0xabc123...",
    "resourceUrl": "https://api.example.com/data",
    "walletId": "WALLET_ID",
    "chainId": "8453"
  }'

Check x402 Budget

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

Add ?sessionId=... if you want the budget view scoped to a single x402 session.

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": "09:00-17:00",
        "timezone": "America/New_York",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAY_OF_WEEK",
        "operator": "IN",
        "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",
        "value": "0xVendorA,0xVendorB,0xVendorC",
        "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": "25",
        "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",
        "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_SESSION_BUDGET",
        "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",
        "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.

MPP Payments

Pre-Authorize an MPP Session

curl -X POST https://conto.finance/api/sdk/mpp/pre-authorize \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "recipientAddress": "0xServiceAddress",
    "resourceUrl": "https://api.service.com/stream",
    "intent": "session",
    "depositAmount": 10.00
  }'

Returns "authorized": true with wallet details, or "authorized": false with violation reasons.

Record an MPP Settlement

After closing a session, record the settled amount:

curl -X POST https://conto.finance/api/sdk/mpp/record \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 3.50,
    "recipientAddress": "0xServiceAddress",
    "txHash": "0xsettlement123...",
    "resourceUrl": "https://api.service.com/stream",
    "sessionId": "mpp_session_xyz",
    "scheme": "mpp",
    "walletId": "WALLET_ID",
    "chainId": "4217"
  }'

Record the settled amount, not the deposit amount.

Check MPP Budget

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

Add ?sessionId=... if you want the budget response scoped to one MPP session.

List MPP Services Used

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

Monitoring

Get Agent Spending Summary

curl https://conto.finance/api/sdk/analytics/spend \
  -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/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, MPP, transaction listing, and wallet queries, use the REST API endpoints shown in 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

​Pre-Authorize an x402 Payment

​Record an x402 Transaction

​Check x402 Budget

​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

​MPP Payments

​Pre-Authorize an MPP Session

​Record an MPP Settlement

​Check MPP Budget

​List MPP Services Used

​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

Pre-Authorize an x402 Payment

Record an x402 Transaction

Check x402 Budget

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

MPP Payments

Pre-Authorize an MPP Session

Record an MPP Settlement

Check MPP Budget

List MPP Services Used

Monitoring

Get Agent Spending Summary

Get Wallet Balance

List Active Alerts

TypeScript SDK Equivalents

Related