> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Copy-paste recipes for the SDK, OpenClaw, Hermes, x402, MPP, approvals, and trust scoring

# 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](/quickstart/setup).

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
curl https://conto.finance/api/organizations/me/members \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

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

```bash theme={null}
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

```bash theme={null}
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`](https://docs.paysponge.com/sdk-reference) under the hood. Set `SPONGE_API_KEY` (and `SPONGE_MASTER_KEY` for fleet management) in your environment.

```bash theme={null}
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:

```bash theme={null}
curl -X POST https://conto.finance/api/wallets/WALLET_ID/provision \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

***

### Link a Wallet to an Agent

```bash theme={null}
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:

```bash theme={null}
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).

```bash theme={null}
# 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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/sdk/x402-payments): pre-authorize, record (including batch), budget, services
* [MPP Payments](/sdk/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.

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

1. Create an approval threshold rule:

```bash theme={null}
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"
      }
    ]
  }'
```

2. Configure a Slack approval channel:

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

***

## Monitoring

### Get Agent Spending Summary

```bash theme={null}
curl "https://conto.finance/api/sdk/analytics?period=month" \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

***

### Get Wallet Balance

```bash theme={null}
curl https://conto.finance/api/sdk/wallets \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

Returns all linked wallets with current balances.

***

### List Active Alerts

```bash theme={null}
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:

```typescript theme={null}
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);
```

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

## Related

<CardGroup cols={3}>
  <Card title="Choose Integration" icon="compass" href="/guides/choose-your-integration">
    SDK vs Agent Skills vs x402 vs MPP
  </Card>

  <Card title="Quickstart" icon="play" href="/quickstart/setup">
    Full setup walkthrough
  </Card>

  <Card title="x402 Payments" icon="bolt" href="/guides/x402-api-payments">
    Pay for APIs with x402
  </Card>

  <Card title="MPP Sessions" icon="clock" href="/guides/mpp-session-payments">
    Session-based micropayments
  </Card>

  <Card title="Approval Workflows" icon="check-to-slot" href="/guides/approval-workflows">
    Add review and escalation controls
  </Card>

  <Card title="Trust Scoring" icon="shield-check" href="/guides/trust-scoring">
    Use counterparty trust as a control surface
  </Card>
</CardGroup>