Agent Sandbox Quickstart

This quickstart is for autonomous agents, coding agents, and agent runtimes that need to evaluate Conto before a human creates a production account. The sandbox signup endpoint creates a test-mode organization, one agent, one Tempo Testnet wallet, an agent SDK key, and a sandbox organization API key. No email verification or human approval is required for sandbox creation.

The anonymous sandbox is for testing only. Returned credentials are shown once, expire after 7 days, and should not be used for real funds or production automation.

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.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, wallet limits, and a machine-readable workflow with setup, request, execute, status, and human-claim actions. Use those links instead of constructing route names from memory.

Create A Sandbox

One command does the whole thing, including writing an owner-only .env.local, updating .gitignore, and adding conto.config.json plus a runnable example.mjs to the current directory:

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

The JSON result identifies the files and environment-variable names but does not print either secret. Read the generated .env.local only inside the runtime that needs those credentials. Or 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

When calling the endpoint directly, the response includes:

Response field	Save it as	Notes
`credentials.sdkKey`	`CONTO_API_KEY`	Bearer token for Conto’s agent SDK
`credentials.apiKey`	`CONTO_SANDBOX_API_KEY`	Sandbox organization key and claim secret
`agent.id`	`CONTO_AGENT_ID`	Created agent ID
`wallet.id`	`CONTO_WALLET_ID`	Created wallet ID
`wallet.address`	`CONTO_WALLET_ADDRESS`	Sender address for external-wallet approval tests
`wallet.custodyMode`	—	`EXTERNAL`; your runtime controls transaction signing
`environment`	—	`sandbox`; no production funds are used
`settlement.mode`	—	`simulated`; receipts are recorded without moving funds
`workflow`	—	Supported next-step methods and URLs

Example extraction:

export CONTO_API_KEY="$(jq -r '.credentials.sdkKey' conto-sandbox.json)"
export CONTO_SANDBOX_API_KEY="$(jq -r '.credentials.apiKey' conto-sandbox.json)"
export CONTO_WALLET_ADDRESS="$(jq -r '.wallet.address' conto-sandbox.json)"

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, and granted scopes. Use it as the runtime probe before attempting payment operations. Payment approval accepts chainId as either the numeric chain ID or the string value returned by setup. The sandbox response reports wallet.custodyMode: "EXTERNAL". Use the approval and confirmation flow when you attach a signer; the basic sandbox execution path remains available for testing policy decisions without an onchain transfer.

Run A Policy-Checked Payment

Sandbox test payments exercise policy evaluation, spend tracking, receipts, and audit logs without an onchain transfer. You do not need a signer or a funded wallet to reach a completed payment. Request a small test payment. The policy engine evaluates it and returns APPROVED, DENIED, or REQUIRES_APPROVAL:

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

The success state for this quickstart is an execute response with "status": "completed". In sandbox test mode, the response omits onchain hash and explorer fields. A GET request to /api/sdk/transactions includes the transaction, which counts against the sandbox spend limits. A request for more than the $5 per-transaction limit returns DENIED with a customer-facing reason, which is the policy engine working as intended.

Bring Your Own Signer (Optional)

If your agent controls a real wallet key, pass its address as publicKey when creating the sandbox and use the external-wallet flow instead: POST /api/sdk/payments/approve returns an approvalToken, your signer performs the testnet transfer, and POST /api/sdk/payments/{requestId}/confirm records the real txHash:

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

Production integrations with managed wallets use the same request -> execute flow with real onchain execution, or autoExecute for single-call payments.

Claim The Sandbox

When a human is ready to keep the sandbox, they sign in to Conto and call the claim endpoint with the sandbox organization API key. The sandbox key can be sent in the JSON body:

curl -sS -X POST https://conto.finance/api/agents/sandbox/claim \
  -H "Content-Type: application/json" \
  -d "{
    \"sandboxApiKey\": \"$CONTO_SANDBOX_API_KEY\"
  }"

The claim request must include a signed-in Conto browser or app session. Claiming transfers the sandbox organization and agent ownership to that verified human account.

Existing Organizations

If a human organization owner has already invited an agent, use organization-token registration instead of anonymous sandbox signup:

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

With a registration token, the agent can join the existing organization and receive a scoped SDK key:

curl -sS -X POST https://conto.finance/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "registrationToken": "registration_token_from_human_owner",
    "name": "Research Buyer Agent",
    "agentType": "CUSTOM",
    "externalId": "research-buyer-prod",
    "callbackUrl": "https://agent.example.com/webhooks/conto"
  }'

externalId is optional but recommended: it makes retries idempotent and gives your system a durable reconciliation key. The response confirms the agent status, granted scopes, credential expiration, and the SDK endpoints that credential can call. The SDK key itself is shown only on the first successful registration. If the same externalId is registered again, Conto returns the existing agent and credential reference without revealing the key again.

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.
Call GET /api/sdk/setup with credentials.sdkKey.
POST /api/sdk/payments/request, then POST /api/sdk/payments/{requestId}/execute.
Verify the execute response shows status: completed without onchain hash or explorer fields.
Ask a human to claim the sandbox before the credentials expire.

Next Steps

Connecting Agents

Wire Conto into OpenAI, Claude, LangChain, Python, and custom runtimes

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

Start

Products

Build

Guides

Reference

Changelog

Agent Sandbox Quickstart

Agent Sandbox Quickstart

Discovery

Create A Sandbox

Inspect The Setup

Run A Policy-Checked Payment

Bring Your Own Signer (Optional)

Claim The Sandbox

Existing Organizations

Agent Checklist

Next Steps

Connecting Agents

Payments API

Custody Modes

OpenAPI

​Agent Sandbox Quickstart

​Discovery

​Create A Sandbox

​Inspect The Setup

​Run A Policy-Checked Payment

​Bring Your Own Signer (Optional)

​Claim The Sandbox

​Existing Organizations

​Agent Checklist

​Next Steps

Connecting Agents

Payments API

Custody Modes

OpenAPI

Agent Sandbox Quickstart

Discovery

Create A Sandbox

Inspect The Setup

Run A Policy-Checked Payment

Bring Your Own Signer (Optional)

Claim The Sandbox

Existing Organizations

Agent Checklist

Next Steps