Skip to main content

​
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:
FieldPurpose
machineReadable.agentSandboxQuickstartThis guide
machineReadable.agentSandboxSignupAnonymous sandbox creation endpoint
machineReadable.agentSandboxClaimHuman claim endpoint
machineReadable.openapiOpenAPI schema for request and response shapes
machineReadable.llmsCompact agent-readable docs index
If your runtime skips manifests, use the endpoint directly: 
curl -sS https://conto.finance/api/agents/sandbox

​
Create A Sandbox

One command does the whole thing, including writing .env.local, conto.config.json, and a runnable example.ts to the current directory: 
npx @conto_finance/create-conto-agent --sandbox --json
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",
    "metadata": {
      "runtime": "codex",
      "reason": "agent-accessibility-test"
    }
  }' > conto-sandbox.json
The response includes:
Response fieldSave it asNotes
credentials.sdkKeyCONTO_API_KEYBearer token for /api/sdk/* endpoints
credentials.apiKeyCONTO_SANDBOX_API_KEYSandbox organization key and claim secret
agent.idCONTO_AGENT_IDCreated agent ID
wallet.idCONTO_WALLET_IDCreated wallet ID
wallet.addressCONTO_WALLET_ADDRESSSender address for external-wallet approval tests
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 Capabilities

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, scopes, and payment endpoints. 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.

​
Run A Policy-Checked Payment

Sandbox payments execute in simulated mode. Policy evaluation, spend tracking, receipts, and audit logs are real; no onchain transfer happens. 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", "simulated": true, and a txHash receipt. The transaction appears in GET /api/sdk/transactions and counts against the sandbox spend limits. A request for more than the $5 per-transaction limit returns DENIED with the violated rule, 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"
  }'

​
Agent Checklist

  1. Fetch /.well-known/agent.json.
  2. Read machineReadable.agentSandboxQuickstart and machineReadable.agentSandboxSignup.
  3. POST /api/agents/sandbox.
  4. Store returned keys securely; they are shown once.
  5. Call GET /api/sdk/setup with credentials.sdkKey.
  6. POST /api/sdk/payments/request, then POST /api/sdk/payments/{requestId}/execute.
  7. Verify the execute response shows status: COMPLETED and simulated: true.
  8. 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 endpoint schemas