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

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:

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

```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"
  }' > 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:

```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 The Setup

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, 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`:

```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"`. 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`:

```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",
    "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

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` without onchain hash or explorer fields.
8. Ask a human to claim the sandbox before the credentials expire.

## Next Steps

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

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

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

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