Recipes

Each recipe assumes you have an active agent with an SDK key. For initial setup, see Quickstart. To create agents, wallets, and SDK keys yourself, see Set up in the dashboard instead, or the Admin SDK for the API. For the same calls in TypeScript, see Send a payment and Code examples. Run payment recipes in the agent’s runtime with its SDK key. Policy and alert recipes use an organization API key.

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

# Org API key (for policy and alert recipes)
export CONTO_ORG_API_KEY="conto_your_org_key_here"

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": "0x0000000000000000000000000000000000000001",
    "purpose": "Service payment"
  }')

REQUEST_ID=$(echo "$REQUEST" | jq -r '.requestId')
echo "$REQUEST" | jq '.status'

# Step 2: Execute the approved request
curl -X POST "https://conto.finance/api/sdk/payments/$REQUEST_ID/execute" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Check payment status

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

Returns one of approved, declined, review_required, processing, reconciliation_required, completed, failed, or expired. For declined and review_required, reasons says why.

List recent transactions

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

x402 and MPP endpoint calls

Each protocol’s API reference documents the pre-authorize, record, and budget/services calls with full request and response shapes:

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

For both protocols, record endpoints use flat top-level settlement fields and optional batchItems for per-call detail. Pass the grantId and grantSignature from the approved pre-authorization to the record call. A record without a valid grant is flagged as a policy bypass and alerts the owner. With an OpenClaw or Hermes skill, the helper covers both x402 calls and requires the grant when recording:

bash skills/conto/conto-check.sh x402 0.05 0xPayee https://api.example.com/v1 "" pay_01J...
bash skills/conto/conto-check.sh x402-record 0.05 0xPayee https://api.example.com/v1 pay_01J... 0xTxHash GRANT_ID GRANT_SIGNATURE

To set the guardrails those endpoints check, start from the x402 or MPP starter policy. The rule reference has the JSON for every x402 and MPP rule.

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": "0x0000000000000000000000000000000000000001",
    "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

A policy created without scope or agentIds applies to every agent in the organization. The recipes below limit each policy to one agent, either with "scope": "assigned" and a separate assignment or with "agentIds": ["AGENT_ID"]. Remove both only when the rule should cover every agent.

Limit an agent to $50 per 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",
    "scope": "assigned",
    "policyType": "SPEND_LIMIT",
    "rules": [
      {
        "ruleType": "DAILY_LIMIT",
        "operator": "LTE",
        "value": "50",
        "action": "ALLOW"
      }
    ]
  }'

Then assign it to the 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" }'

Restrict payments by agent identity

Use identity rules to require a production, low-risk agent with a finance tag and hardware attestation. Missing identity context fails closed for these allow rules.

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Finance Agents",
    "agentIds": ["AGENT_ID"],
    "policyType": "COMPOSITE",
    "rules": [
      {
        "ruleType": "AGENT_ENVIRONMENT",
        "operator": "IN_LIST",
        "value": "{\"environments\":[\"PROD\"]}",
        "action": "ALLOW"
      },
      {
        "ruleType": "AGENT_RISK_TIER",
        "operator": "IN_LIST",
        "value": "{\"riskTiers\":[\"LOW\",\"MEDIUM\"]}",
        "action": "ALLOW"
      },
      {
        "ruleType": "AGENT_OWNER_ROLE",
        "operator": "IN_LIST",
        "value": "{\"roles\":[\"OWNER\",\"ADMIN\"]}",
        "action": "ALLOW"
      },
      {
        "ruleType": "AGENT_TAG",
        "operator": "IN_LIST",
        "value": "{\"tags\":[\"finance\"]}",
        "action": "ALLOW"
      },
      {
        "ruleType": "ATTESTATION_LEVEL",
        "operator": "IN_LIST",
        "value": "{\"attestationModes\":[\"HARDWARE\"]}",
        "action": "ALLOW"
      }
    ]
  }'

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",
    "agentIds": ["AGENT_ID"],
    "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",
    "agentIds": ["AGENT_ID"],
    "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",
    "agentIds": ["AGENT_ID"],
    "policyType": "COUNTERPARTY",
    "rules": [
      {
        "ruleType": "ALLOWED_COUNTERPARTIES",
        "operator": "IN_LIST",
        "value": "[\"0x1234567890abcdef1234567890abcdef12345678\", \"0xabcdef1234567890abcdef1234567890abcdef12\"]",
        "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",
    "agentIds": ["AGENT_ID"],
    "policyType": "COMPOSITE",
    "rules": [
      {
        "ruleType": "MPP_ALLOWED_SERVICES",
        "operator": "IN_LIST",
        "value": "[\"api.service.com\", \"streaming.provider.io\"]",
        "action": "ALLOW"
      }
    ]
  }'

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

Notify Slack about large payments

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",
    "agentIds": ["AGENT_ID"],
    "policyType": "APPROVAL_THRESHOLD",
    "rules": [
      {
        "ruleType": "REQUIRE_APPROVAL_ABOVE",
        "operator": "GREATER_THAN",
        "value": "500",
        "action": "REQUIRE_APPROVAL"
      }
    ]
  }'

Add a Slack notification channel with the approval.requested event.

Slack posts each request with a Review in Conto link. Approvers decide in the dashboard or from the email link. See approval notifications for channel setup.

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?status=open" \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"

Get started

Integrate

Payments

Agentic commerce

Spending controls

Operate

Conto Pay

Payments

Request and execute a payment

Check payment status

List recent transactions

x402 and MPP endpoint calls

Approve and confirm an external wallet payment

Policies

Limit an agent to $50 per day

Restrict payments by agent identity

Require approval above $100

Block payments outside business hours

Allowlist specific recipients

Restrict MPP to allowed services

Approvals and trust

Look up trust for a counterparty address

Notify Slack about large payments

Monitoring

Get agent spending summary

Get wallet balance

List active alerts

​Payments

​Request and execute a payment

​Check payment status

​List recent transactions

​x402 and MPP endpoint calls

​Approve and confirm an external wallet payment

​Policies

​Limit an agent to $50 per day

​Restrict payments by agent identity

​Require approval above $100

​Block payments outside business hours

​Allowlist specific recipients

​Restrict MPP to allowed services

​Approvals and trust

​Look up trust for a counterparty address

​Notify Slack about large payments

​Monitoring

​Get agent spending summary

​Get wallet balance

​List active alerts

Payments

Request and execute a payment

Check payment status

List recent transactions

x402 and MPP endpoint calls

Approve and confirm an external wallet payment

Policies

Limit an agent to $50 per day

Restrict payments by agent identity

Require approval above $100

Block payments outside business hours

Allowlist specific recipients

Restrict MPP to allowed services

Approvals and trust

Look up trust for a counterparty address

Notify Slack about large payments

Monitoring

Get agent spending summary

Get wallet balance

List active alerts