Try the sandbox

Try Conto without an account, from a terminal or an autonomous agent. A new sandbox starts with default limits of

5 per payment and

25 per day. A payment within them returns APPROVED, and one above them returns DENIED. The sandbox setup key lets you change those limits and add policies, including merchant and category rules and a rule that holds a payment for human approval. If an organization owner has already invited your agent, register with their token instead. Sandbox signup creates a test-mode organization, one agent, one Tempo Testnet wallet, an agent SDK key, a sandbox organization API key, and a sandbox setup key, with no email verification or human approval. Settlement is simulated: no onchain transfer occurs, a test receipt is not an explorer receipt, and you do not need to fund the wallet.

The anonymous sandbox is for testing only. Returned credentials are shown once and expire after 7 days.

Discovery

Start from the agent manifest:

curl -sS https://conto.finance/.well-known/agent.json

Read these fields:

Field	Purpose
`machineReadable.agentSandboxQuickstart`	This guide
`machineReadable.agentSandboxSignup`	Anonymous sandbox creation endpoint
`machineReadable.agentSandboxHandoff`	Browser handoff for a person to claim the sandbox
`machineReadable.agentSandboxClaim`	Human claim endpoint
`machineReadable.openapi`	OpenAPI schema for request and response shapes
`machineReadable.llms`	Compact agent-readable docs index

If your runtime skips manifests, use the endpoint directly:

curl -sS https://conto.finance/api/agents/sandbox

The descriptor includes environment, simulated-settlement semantics, the default wallet limits, and a machine-readable workflow with setup, request, execute, status, human-claim, and control-configuration actions. Each control action names the credential it needs. Use those links instead of building route names from memory.

Create a sandbox

One command creates the sandbox, writes an owner-only .env.local, updates .gitignore, and adds conto.config.json and a runnable example.mjs to the current directory:

npx @conto_finance/create-conto-agent --sandbox --json

.env.local holds the agent SDK key and the sandbox API key. The CLI writes the setup key to a separate owner-only file, .conto/sandbox-setup.env, and adds .conto/ to .gitignore, so the payment runtime that loads .env.local never receives it. The JSON result reports file locations and environment-variable names (credentials.setupKeyStoredIn and credentials.setupKeyEnv) but prints no secret. If the result has no setupKeyStoredIn, your CLI version predates setup keys. Update the package, or create the sandbox with the API call below. To test from Python 3.10+, run the CLI command above (it needs Node.js 20.19+), then use the Python starter from the same directory. It calls Conto’s HTTP API and needs no Python dependencies.

Download it: curl -fsS https://conto.finance/examples/conto-sandbox.py -o conto-sandbox.py
Run python3 conto-sandbox.py to check setup. It prints the agent name and scopes and creates no payment.
Run python3 conto-sandbox.py --execute to make one test payment. The script executes only in a CLI-created simulated sandbox. It creates one payment intent for 0.01, prints its request ID, and executes only if the policy decision is APPROVED. Success prints Status: completed and Settlement mode: test. The test receipt records the workflow without transferring funds.
Each --execute run creates a new intent. After a timeout, inspect the original request with python3 conto-sandbox.py --status REQUEST_ID instead of executing again. In production, store the request ID before executing.

To create the sandbox without the CLI, call the endpoint directly:

curl -sS -X POST https://conto.finance/api/agents/sandbox \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Buyer Agent",
    "agentType": "CUSTOM",
    "description": "Tests policy-checked payments from an autonomous agent"
  }' > conto-sandbox.json

The endpoint’s response includes:

Response field	Save it as	Notes
`credentials.sdkKey`	`CONTO_API_KEY`	Bearer token for Conto’s agent SDK. The payment runtime’s only key
`credentials.apiKey`	`CONTO_SANDBOX_API_KEY`	Read-only sandbox organization key. Used for handoff and claim
`credentials.setupKey`	`CONTO_SANDBOX_SETUP_KEY`	Configures this sandbox’s controls. Keep it out of the agent
`agent.id`	`CONTO_AGENT_ID`	Created agent ID
`wallet.id`	`CONTO_WALLET_ID`	Created wallet ID
`wallet.address`	None	Placeholder address. No one holds its key
`wallet.custodyMode`	None	`EXTERNAL`. Sandbox execution is simulated, so no signer is needed
`environment`	None	`sandbox`. No production funds are used
`settlement.mode`	None	`simulated`. Receipts are recorded without moving funds
`workflow`	None	Supported next-step methods and URLs

Example extraction into one owner-only file per role:

umask 077
jq -r '"CONTO_API_KEY=\(.credentials.sdkKey)"' conto-sandbox.json > agent.env
jq -r '"CONTO_SANDBOX_SETUP_KEY=\(.credentials.setupKey)",
       "CONTO_SANDBOX_API_KEY=\(.credentials.apiKey)"' conto-sandbox.json > setup.env
export CONTO_AGENT_ID="$(jq -r '.agent.id' conto-sandbox.json)"
export CONTO_WALLET_ID="$(jq -r '.wallet.id' conto-sandbox.json)"
rm conto-sandbox.json

Load agent.env in the payment agent’s runtime and setup.env only where you configure controls. The commands below assume the relevant file is loaded, for example with set -a; . ./setup.env; set +a.

Credential roles

Credential	Prefix	Held by	Can	Cannot
SDK key	`conto_agent_`	The payment agent	Read its effective controls, request payments, execute approved payments, check payment status	Change controls, approve a held payment, claim the sandbox
Setup key	`conto_setup_`	The person or coding assistant preparing the test	Read and change this sandbox’s policies, policy rules, policy assignments, and agent-wallet spend limits	Request, execute, or approve payments. Create wallets or keys. Change team, billing, or settings. Reach another organization
Sandbox API key	`conto_`	Whoever offers the claim link	Read the sandbox organization, create a claim handoff	Write anything
Human owner	Signed-in user	The person who claims the sandbox	Review held payments, edit controls in Conto	Turn the sandbox into a live organization

All keys are stored hashed and expire with the sandbox after 7 days. A human claim revokes the setup key. From then on, the owner changes controls in Conto. A coding assistant can apply the test configuration a person asked for with the setup key, then run the payment agent with only the SDK key. The setup key never belongs in the agent’s environment, prompt, or tool configuration.

Configure controls

The setup key works only on these routes, only for its own sandbox, and only until a human claims it. Other organization routes return 403 with code: "SANDBOX_SETUP_SCOPE", and payment routes reject it. An ID from another organization returns 404.

Method	Route	Purpose
`GET`, `PATCH`	`/api/agents/{agentId}/wallets/{walletId}`	Read and change spend limits and allowed hours
`GET`	`/api/agents/{agentId}/wallets`	List the agent’s wallet links
`GET`, `POST`	`/api/policies`	List and create policies
`GET`, `PATCH`	`/api/policies/{policyId}`	Read, rename, reprioritize, activate, deactivate
`GET`, `POST`, `PUT`	`/api/policies/{policyId}/rules`	Read, add, or replace a policy’s rules
`GET`, `PATCH`, `DELETE`	`/api/policies/{policyId}/rules/{ruleId}`	Read, change, or remove one rule
`GET`	`/api/policies/{policyId}/versions`	Read the policy’s change history
`GET`, `POST`, `DELETE`	`/api/agents/{agentId}/policies`	Read, assign, and unassign the agent’s policies

These are the same routes, validators, audit log, and policy history that account-backed organizations use. See Policy rules for every rule type.

Change spend limits

curl -sS -X PATCH "https://conto.finance/api/agents/$CONTO_AGENT_ID/wallets/$CONTO_WALLET_ID" \
  -H "Authorization: Bearer $CONTO_SANDBOX_SETUP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spendLimitPerTx": 20, "spendLimitDaily": 60 }'

The setup key can send spendLimitPerTx, spendLimitDaily, spendLimitWeekly, spendLimitMonthly, allowedHoursStart, allowedHoursEnd, allowedDays, and timezone. Limits accept 0 through 10000, or null for no limit on that window. Other fields, such as isActive or delegationType, return 403. Wallet limits are hard limits: an approval rule cannot override them.

Restrict merchants and categories

Create a policy and assign it to the agent:

curl -sS -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_SANDBOX_SETUP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Approved merchants",
    "policyType": "COUNTERPARTY",
    "scope": "assigned",
    "rules": [
      {
        "ruleType": "ALLOWED_COUNTERPARTIES",
        "operator": "IN_LIST",
        "value": "[{\"type\":\"address\",\"value\":\"0x1111111111111111111111111111111111111111\",\"label\":\"Merchant A\"}]",
        "action": "ALLOW"
      },
      {
        "ruleType": "BLOCKED_CATEGORIES",
        "operator": "IN_LIST",
        "value": "[\"gambling\"]",
        "action": "DENY"
      }
    ]
  }' > policy.json

curl -sS -X POST "https://conto.finance/api/agents/$CONTO_AGENT_ID/policies" \
  -H "Authorization: Bearer $CONTO_SANDBOX_SETUP_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"policyId\": \"$(jq -r '.id' policy.json)\" }"

Counterparty rules match the payment’s recipientAddress. Category rules match the category the agent sends with the request. That value is agent-supplied, not a verified merchant category. A payment that omits category is denied by any category rule.

Require human approval

curl -sS -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_SANDBOX_SETUP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review purchases over $10",
    "policyType": "APPROVAL_THRESHOLD",
    "scope": "assigned",
    "rules": [
      {
        "ruleType": "REQUIRE_APPROVAL_ABOVE",
        "operator": "GREATER_THAN",
        "value": "10",
        "action": "REQUIRE_APPROVAL"
      }
    ]
  }'

Assign it the same way. A rule’s action defaults to ALLOW, so set REQUIRE_APPROVAL explicitly. Keep the per-payment limit above the approval threshold, or the limit denies the payment before review.

Change or turn off a policy

Replace a policy’s rules with PUT /api/policies/{policyId}/rules and a rules array, or turn the policy off with PATCH /api/policies/{policyId} and { "isActive": false }. A change applies to the next evaluation. Policy and rule changes are recorded in the policy’s history and the audit log. Limit and assignment changes are recorded in the audit log.

Quotas and the simulated balance

A sandbox holds up to 25 policies with up to 50 rules each. Reaching a quota returns 409 with code: "SANDBOX_POLICY_QUOTA" or "SANDBOX_RULE_QUOTA". The wallet’s $100 test balance is fixed, and the setup key cannot add to it. A payment larger than the remaining balance is denied with the reason The available balance is insufficient for this payment., not a spending-limit reason.

What the agent sees

The payment agent reads its effective controls with its own SDK key: GET /api/sdk/setup, GET /api/sdk/spending-limits, and GET /api/sdk/policies. It cannot change them.

Inspect the setup

Use the SDK key returned by sandbox signup:

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

This returns the authenticated agent, available wallets, spend limits, granted scopes, and versioned setup diagnostics. Call it as the runtime probe before any payment operation. In a new sandbox, diagnostics.environment.kind is anonymous_sandbox, and the SANDBOX_UNCLAIMED issue tells you a person has not claimed it yet. After a claim, the kind is claimed_sandbox. In a CLI-created project, npx @conto_finance/create-conto-agent doctor --json prints the same diagnostics.

Run a policy-checked payment

Request a small test payment. Conto evaluates it and returns the decision in status:

curl -sS -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 3,
    "recipientAddress": "0x0000000000000000000000000000000000000001",
    "recipientName": "Test Vendor",
    "purpose": "Sandbox API credits",
    "category": "AI_SERVICES"
  }' > payment-request.json

export REQUEST_ID="$(jq -r '.requestId' payment-request.json)"

If the status is APPROVED, execute it:

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

Success is an execute response with "status": "completed" and receipt.settlementMode: "test". The receipt includes a Conto transactionId and omits txHash and the explorer URL. Status and transaction endpoints repeat the settlement mode. test never proves an onchain transfer. GET /api/sdk/transactions includes the transaction, which counts against the configured spend limits. With the default limits, a request over

5, or over

25 in a day, returns DENIED with a reason. A denied request never executes and never spends. To make retries safe, send an idempotencyKey with each purchase. The same request with the same key returns the original request. The same key with different input returns 409. Give a changed purchase, including a retry after you change a control, a new key. If an execute call ends without a response, check GET /api/sdk/payments/{requestId} before doing anything else. Do not execute again blindly.

Human review

A payment that matches a REQUIRE_APPROVAL rule returns "status": "REQUIRES_APPROVAL" and an approvalRequestId. It stays pending and does not execute. No machine credential can approve it: the review routes refuse the SDK key, the setup key, and the sandbox API key. To finish the review, a person claims the sandbox:

Create a claim link with the handoff below and send verificationUrl to the person.
The person signs in, claims the sandbox, switches to the sandbox organization in Conto, and opens Alerts & Approvals, then Approvals.
The person approves or rejects the payment.

The agent polls GET /api/sdk/payments/{requestId} with its SDK key. It does not call execute while the payment waits.

Approved. Conto rechecks the payment against the current controls and records a simulated test payment. The agent sees "status": "completed" and "settlementMode": "test".
Rejected. The agent sees "status": "declined". Nothing is spent.
Controls changed while it waited. The recheck applies the current controls, so an approved payment can still end as declined.
No decision. The request expires after 24 hours.

An unclaimed sandbox has no reviewer, so a held payment stays pending until someone claims it.

Simulation boundary

Every payment executed in a sandbox is simulated, whatever wallet it uses. No custody provider is called, and receipts carry settlementMode: "test" with no transaction hash or explorer link. Spend counters and the test balance use the same reservation and accounting as live payments. Claiming does not change this: a sandbox organization cannot create managed wallets, set up Conto Pay, or change plans, and connected cards are not available in a sandbox. To use real funds, create a Conto organization. The optional external signer flow below is separate: your own wallet signs that transfer, and Conto never executes it.

Bring your own signer (optional)

If your agent controls a real Tempo Testnet wallet, call POST /api/sdk/payments/approve with amount, recipientAddress, your wallet as senderAddress, and chainId: 42431. An approved response returns approvalToken and confirmUrl:

curl -sS -X POST https://conto.finance/api/sdk/payments/approve \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"amount\": 1,
    \"recipientAddress\": \"0x0000000000000000000000000000000000000001\",
    \"senderAddress\": \"$MY_WALLET_ADDRESS\",
    \"chainId\": 42431
  }" > approval.json

export APPROVAL_TOKEN="$(jq -r '.approvalToken' approval.json)"
export CONFIRM_URL="$(jq -r '.confirmUrl' approval.json)"

Conto registers your wallet with the external-wallet defaults, not the

5 and

25 sandbox limits. Send the transfer from your wallet, then post the txHash and approvalToken to confirmUrl:

curl -sS -X POST "https://conto.finance$CONFIRM_URL" \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"txHash\": \"$TX_HASH\",
    \"approvalToken\": \"$APPROVAL_TOKEN\"
  }"

See the external-wallet flow for token expiry and the SDK methods.

Hand off to a person from a remote agent

Use this flow when your agent runs on a server, in CI, or on another device. It requires no localhost callback and never places the sandbox API key in a browser link. In a CLI-created project, one command creates the link and keeps the polling token in an owner-only file:

npx @conto_finance/create-conto-agent sandbox claim --json
npx @conto_finance/create-conto-agent sandbox claim --wait --timeout 300 --json

See sandbox handoff for its exit codes. The API calls below do the same without the CLI.

umask 077
curl --fail-with-body -sS -X POST https://conto.finance/api/agents/sandbox/handoff \
  -H "Authorization: Bearer $CONTO_SANDBOX_API_KEY" > conto-handoff.json

Send only verificationUrl to the person who will own the sandbox. Treat that URL and the returned token as temporary secrets: keep them out of logs and public messages. The URL expires in at most 15 minutes. The person signs in, verifies their email, reviews the sandbox name and ownership permission, and explicitly chooses Claim sandbox. Poll statusUrl using the handoff token (not the SDK or sandbox key). Wait at least the returned intervalSeconds between checks. Stop on claimed or on expiry. Do not repeatedly create grants.

export CONTO_HANDOFF_TOKEN="$(jq -r '.token' conto-handoff.json)"
curl --fail-with-body -sS https://conto.finance/api/agents/sandbox/handoff \
  -H "Authorization: Bearer $CONTO_HANDOFF_TOKEN"

status: "claimed" completes the handoff and revokes the setup key. It does not enable production payments, fund a wallet, change spending limits, or extend the sandbox credentials. Delete the handoff file when done. Review production readiness before using real funds.

Agent checklist

Fetch /.well-known/agent.json.
Read machineReadable.agentSandboxQuickstart and machineReadable.agentSandboxSignup.
POST /api/agents/sandbox.
Store returned keys securely. They are shown once. Give the payment runtime only credentials.sdkKey. Keep credentials.setupKey with the setup step.
Optionally configure limits and policies with the setup key.
Call GET /api/sdk/setup with credentials.sdkKey.
POST /api/sdk/payments/request with an idempotencyKey, then POST /api/sdk/payments/{requestId}/execute for an APPROVED result.
Verify status: "completed" and receipt.settlementMode: "test". Expect no hash or explorer URL in a new simulated receipt.
For REQUIRES_APPROVAL, hand off to a person and poll the payment status.
Before the credentials expire, POST /api/agents/sandbox/handoff, or run sandbox claim with the CLI, and send the returned verificationUrl to a person.

Next steps

Code examples

SDK, OpenAI, Anthropic, Python, and server examples

Payments API

Request, approve, execute, confirm, and inspect payment state

Custody modes

Choose managed execution or external-wallet approval flows

OpenAPI

Generate clients and inspect request and response schemas

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Try the sandbox

Discovery

Create a sandbox

Credential roles

Configure controls

Change spend limits

Restrict merchants and categories

Require human approval

Change or turn off a policy

Quotas and the simulated balance

What the agent sees

Inspect the setup

Run a policy-checked payment

Human review

Simulation boundary

Bring your own signer (optional)

Hand off to a person from a remote agent

Agent checklist

Next steps

Code examples

Payments API

Custody modes

OpenAPI

​Discovery

​Create a sandbox

​Credential roles

​Configure controls

​Change spend limits

​Restrict merchants and categories

​Require human approval

​Change or turn off a policy

​Quotas and the simulated balance

​What the agent sees

​Inspect the setup

​Run a policy-checked payment

​Human review

​Simulation boundary

​Bring your own signer (optional)

​Hand off to a person from a remote agent

​Agent checklist

​Next steps

Code examples

Payments API

Custody modes

OpenAPI

Discovery

Create a sandbox

Credential roles

Configure controls

Change spend limits

Restrict merchants and categories

Require human approval

Change or turn off a policy

Quotas and the simulated balance

What the agent sees

Inspect the setup

Run a policy-checked payment

Human review

Simulation boundary

Bring your own signer (optional)

Hand off to a person from a remote agent

Agent checklist

Next steps