> ## 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.

# Agent Sandbox Quickstart

> Let an AI agent discover Conto, create a test-mode sandbox without human intervention, inspect its setup, and try a policy-checked payment flow.

# 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.

<Warning>
  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.
</Warning>

## Discovery

Start from the agent manifest:

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

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

```bash theme={null}
npx @conto_finance/create-conto-agent --sandbox --json
```

Or call the endpoint directly:

```bash theme={null}
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 field       | Save it as              | Notes                                             |
| -------------------- | ----------------------- | ------------------------------------------------- |
| `credentials.sdkKey` | `CONTO_API_KEY`         | Bearer token for `/api/sdk/*` endpoints           |
| `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 |

Example extraction:

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

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

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

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

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

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

## 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:

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

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

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

<CardGroup cols={2}>
  <Card title="Connecting Agents" icon="plug" href="/quickstart/connecting-agents">
    Wire Conto into OpenAI, Claude, LangChain, Python, and custom runtimes
  </Card>

  <Card title="Payments API" icon="code" href="/sdk/payments">
    Request, approve, execute, confirm, and inspect payment state
  </Card>

  <Card title="Custody Modes" icon="wallet" href="/guides/custody-modes">
    Choose managed execution or external-wallet approval flows
  </Card>

  <Card title="OpenAPI" icon="route" href="/api/reference">
    Generate clients and inspect endpoint schemas
  </Card>
</CardGroup>