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

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.

​
Try A Policy Check

Anonymous sandboxes use an external wallet in SDK_REQUIRED mode. The agent keeps signing authority, and Conto provides policy approval, auditability, and confirmation tracking. Ask Conto to approve a small test payment: 
curl -sS -X POST https://conto.finance/api/sdk/payments/approve \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"amount\": 3,
    \"senderAddress\": \"$CONTO_WALLET_ADDRESS\",
    \"recipientAddress\": \"0x742d35Cc6634C0532925a3b844Bc454e4438f44e\",
    \"recipientName\": \"Test Vendor\",
    \"purpose\": \"Sandbox API credits\",
    \"category\": \"AI_SERVICES\",
    \"chainId\": 42431
  }"
If the response is approved, it includes an approvalToken and request ID. Your own signer or wallet stack performs the testnet transfer, then confirms it: 
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\"
  }"
For managed wallets, production integrations can use request -> execute or autoExecute. Anonymous sandboxes intentionally start with the external-wallet approve -> transfer -> confirm flow so an agent can test Conto without custodial setup.

​
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 '{
    "token": "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. Use POST /api/sdk/payments/approve for sandbox external-wallet policy checks.
  7. Confirm executed transfers with POST /api/sdk/payments/{requestId}/confirm.
  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