Skip to main content

​
Recipes

Quick, self-contained solutions for specific tasks. Each recipe assumes you have an active agent with an SDK key. For initial setup, see Your First Agent Payment. 
# All recipes use this variable
export CONTO_API_KEY="conto_agent_your_key_here"

​
Setup

​
Create an Agent via API

curl -X POST https://conto.finance/api/agents \
  -H "Authorization: Bearer $CONTO_ORG_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_org_...) 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_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "scopes": ["payments:request", "payments:execute", "wallets:read", "transactions:read"]
  }'
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_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Ops Wallet",
    "chainType": "EVM",
    "custodyType": "SPONGE"
  }'
Then provision it to generate an on-chain address: 
curl -X POST https://conto.finance/api/wallets/WALLET_ID/provision \
  -H "Authorization: Bearer $CONTO_ORG_KEY"

curl -X POST https://conto.finance/api/agents/AGENT_ID/wallets \
  -H "Authorization: Bearer $CONTO_ORG_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 (on-chain 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"

​
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",
    "serviceDomain": "api.example.com"
  }'
Returns "authorized": true with wallet details, or "authorized": false with violation reasons.

​
Record an x402 Transaction

After the x402 payment executes on-chain: 
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",
    "transactionHash": "0xabc123...",
    "resourceUrl": "https://api.example.com/data",
    "serviceDomain": "api.example.com",
    "walletId": "WALLET_ID",
    "chainId": "8453"
  }'

​
Check x402 Budget

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

​
Policies

​
Limit Agent to $50/Day

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_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_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_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_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours Only",
    "policyType": "TIME_RESTRICTION",
    "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_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_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "x402 Guardrails",
    "policyType": "X402_CONTROLS",
    "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_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "x402 Service Allowlist",
    "policyType": "X402_CONTROLS",
    "rules": [
      {
        "ruleType": "X402_ALLOWED_SERVICES",
        "value": "api.example.com,data.provider.io",
        "action": "ALLOW"
      }
    ]
  }'

​
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_KEY"

​
TypeScript SDK Equivalents

The recipes above use curl. Here are the same operations in TypeScript: 
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);

// List transactions
const txns = await conto.transactions.list();

// x402 pre-authorize
const auth = await conto.x402.preAuthorize({
  amount: 0.05,
  recipientAddress: '0x...',
  resourceUrl: 'https://api.example.com/data',
  serviceDomain: 'api.example.com',
});

// Get wallets and balances
const wallets = await conto.wallets.list();

First Payment

Full setup walkthrough

Test Payments

Validate policy enforcement

Secure Agents

Production policy configuration