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

# Quickstart

> Create an account, connect an agent, fund a Tempo Testnet wallet, and make your first policy-checked payment. No real funds required.

# Quickstart

End-to-end setup on **Tempo Testnet**. By the end you'll have a Conto organization, an AI agent, a funded testnet wallet, two test policies, and a verified onchain payment.

Total time: about 10 minutes. No real funds required.

## What you'll build

<Check>A Conto organization with your account</Check>
<Check>An AI agent connected in Conto</Check>
<Check>A Tempo Testnet wallet funded with pathUSD</Check>
<Check>Spending policies that approve, require approval, or deny payments</Check>
<Check>A verified test payment on Tempo Testnet</Check>

## Why Tempo Testnet?

Tempo Testnet pays transaction fees in `pathUSD` itself, so you don't need a separate gas token. Combined with free faucet funds, it's the fastest way to test the full flow.

| Property | Value                                                            |
| -------- | ---------------------------------------------------------------- |
| Network  | Tempo Testnet                                                    |
| Chain ID | `42431`                                                          |
| Currency | `pathUSD` (TIP-20)                                               |
| Gas      | Paid in `pathUSD`. No separate gas token.                        |
| Explorer | [`explore.testnet.tempo.xyz`](https://explore.testnet.tempo.xyz) |

## Alternate path: CLI-first setup

Prefer the command line? The CLI can create the agent, wallet, starter policy, SDK key, and local
example for you:

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

For CI or autonomous agent runs, use the sandbox JSON mode:

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

Then verify the generated project and run its example:

```bash theme={null}
npx conto doctor
node example.mjs
node example.mjs --execute
```

Use the dashboard/API steps below when you want to see or customize each resource yourself. For the
full command reference, see [CLI quickstart](/cli/quickstart).

## Choose Your Key Up Front

Most developers need both of these at different points in the integration:

| Use case                                                                            | Credential                         | Env var             |
| ----------------------------------------------------------------------------------- | ---------------------------------- | ------------------- |
| Create agents, link wallets, assign policies, or repair ownership from your backend | Organization API key (`conto_...`) | `CONTO_ORG_API_KEY` |
| Let the agent call `/api/sdk/*` payment and read endpoints                          | Agent SDK key (`conto_agent_...`)  | `CONTO_API_KEY`     |

<Info>
  If your app provisions agents for end users, create the agent with an org API key first, then hand
  the agent its own SDK key for runtime payment calls.
</Info>

## Step 1. Create your account

1. Visit [conto.finance](https://conto.finance) and sign up with your name, email, password, and an **organization name**. The organization is the top-level container for agents, wallets, and policies.
2. Verify your email using the link we send you, then sign in. Sign-in is blocked until the email is verified.

## Step 2. Create and fund a wallet

<Steps>
  <Step title="Create the wallet">
    Sidebar > **Wallets > Create Wallet**.

    | Field                 | Value                                                         |
    | --------------------- | ------------------------------------------------------------- |
    | Wallet Name           | `Test Operations Wallet`                                      |
    | Blockchain Network    | **EVM Chains** tab > Tempo Testnet (the pre-selected default) |
    | Wallet Type           | Standard Wallet (EOA)                                         |
    | Custody & Enforcement | **Privy-Managed** (recommended)                               |

    Conto assigns the onchain address as soon as the wallet is created; the dialog shows it
    immediately.

    <Info>
      After creation, the dialog offers an inline **Assign to Agent** step. You can skip it for
      now. Step 4 links the wallet from the agent's side.
    </Info>
  </Step>

  <Step title="Fund with the faucet">
    On the wallet card, open the menu and click **Fund Wallet**, then **Request Testnet Tokens**.
    Free testnet `pathUSD` arrives in seconds.
  </Step>
</Steps>

For Sponge-managed custody, smart-contract wallets, or importing an existing external wallet (watch-only), see [Custody modes](/guides/custody-modes).

## Step 3. Connect an agent

<Steps>
  <Step title="Open Agents">
    Sidebar > **Agents > Connect Agent**.
  </Step>

  <Step title="Fill in details">
    | Field                 | Example                            |
    | --------------------- | ---------------------------------- |
    | Display Name          | `Test Payment Agent`               |
    | Agent Platform        | `Custom Agent` (or your framework) |
    | Purpose / Description | `Quickstart test agent`            |

    Owner, Environment, and Risk Tier are pre-filled with sensible defaults.
  </Step>

  <Step title="Connect">
    Click **Connect Agent**. The agent starts in `ACTIVE` status.

    <Info>
      Connect Agent is a short wizard: after the details step it offers to link a funding wallet
      and assign policies inline. Completing those there is equivalent to Steps 4 and 6 below.
    </Info>
  </Step>
</Steps>

Via API:

If you create agents through the API, every agent gets an owner. Omit `ownerMembershipId` and
Conto assigns the organization's highest-priority member (owner first). To pick a specific owner,
first fetch one stable membership id for your org:

```bash theme={null}
curl https://conto.finance/api/organizations/me/members \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

Pick `members[].id` for the org member or service account that should own the agent, then create
the agent:

```bash theme={null}
curl -X POST https://conto.finance/api/agents \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Payment Agent",
    "agentType": "CUSTOM",
    "description": "Quickstart test agent",
    "ownerMembershipId": "cm0abc123..."
  }'
```

Valid `agentType` values: `OPENAI_ASSISTANT`, `ANTHROPIC_CLAUDE`, `LANGCHAIN`, `AUTOGPT`, `CUSTOM`. Agent statuses: `ACTIVE`, `PAUSED`, `SUSPENDED`, `REVOKED`.

## Step 4. Link the wallet to the agent

<Steps>
  <Step title="Link the wallet">
    Open the agent detail page. In the **Wallets** tab, click **Link Wallet** and pick the Tempo Testnet wallet.
  </Step>

  <Step title="Set spending limits">
    Recommended for the quickstart:

    | Setting         | Value  |
    | --------------- | ------ |
    | Per Transaction | `50`   |
    | Daily Limit     | `500`  |
    | Weekly Limit    | `2000` |
    | Monthly Limit   | `5000` |

    <Warning>
      Don't use Per Transaction `0` as a kill switch. Wallet-level spend limits treat `0` as
      unlimited. Use a positive limit for a cap, or suspend the agent when you need to block spend.
    </Warning>
  </Step>
</Steps>

Default limits, time windows, and other agent-wallet link defaults are listed on the [Defaults](/reference/defaults) page.

## Step 5. Generate an SDK key

<Steps>
  <Step title="Open SDK Integration">
    On the agent detail page, click the **SDK Integration** tab.
  </Step>

  <Step title="Generate the key">
    Click **Generate SDK Key**. Name it (e.g. `Testnet Key`). Keep the default expiration (1 year)
    and the default **Standard** key type. Standard keys cover everything in this guide: they
    include `payments:request` for policy evaluation and `payments:execute` for Step 8's
    `POST /api/sdk/payments/{requestId}/execute` call. Reserve **Admin** keys for agents that
    also manage agents, wallets, or policies.
  </Step>

  <Step title="Store the key immediately">
    The full key is shown once. Save it to your environment:

    ```bash theme={null}
    export CONTO_API_KEY="conto_agent_your_key_here"
    ```
  </Step>
</Steps>

For scopes and key types (`standard` vs `admin`), see [Authentication](/sdk/authentication).

Verify the setup:

```bash theme={null}
curl https://conto.finance/api/sdk/setup \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

You should see:

* `agent.status` is `"ACTIVE"`
* `wallets` contains your Tempo Testnet wallet with a balance
* `scopes` includes `payments:request` and `payments:execute` (both are part of the standard
  preset)

## Step 6. Create two test policies

These two policies together produce three different payment outcomes:

### Policy A: spend limit

<Steps>
  <Step title="Create the policy">
    Sidebar > **Policies > Create Policy**.

    | Field       | Value                       |
    | ----------- | --------------------------- |
    | Policy Name | `Test Spend Limit`          |
    | Policy Type | `Spend Limit`               |
    | Description | Deny transactions over \$15 |
  </Step>

  <Step title="Set the limit">
    Set **Max Transaction (\$)** to `15`. Leave the daily, weekly, and monthly fields empty.

    The **Rules to be created** preview shows the generated rule: `MAX_AMOUNT` / `LTE` / `15` /
    `ALLOW`. Amounts at or under \$15 pass; anything above is denied.
  </Step>
</Steps>

### Policy B: approval threshold

<Steps>
  <Step title="Create the policy">
    Sidebar > **Policies > Create Policy**.

    | Field       | Value                                       |
    | ----------- | ------------------------------------------- |
    | Policy Name | `Test Approval Threshold`                   |
    | Policy Type | `Approval Threshold`                        |
    | Description | Require approval for transactions over \$10 |
  </Step>

  <Step title="Set the threshold">
    Set **Require Approval Above (\$)** to `10`.

    The generated rule is `REQUIRE_APPROVAL_ABOVE` / `GREATER_THAN` / `10` / `REQUIRE_APPROVAL`:
    anything over \$10 pauses for human approval.
  </Step>
</Steps>

### Assign both to the agent

Open the agent detail page > **Permissions** tab > **Assign Policy** > assign **Test Spend Limit** and **Test Approval Threshold**.

Policies combine with AND logic. The most restrictive outcome wins. Higher priority numbers evaluate first (default priority is `50`).

## Step 7. Run three test transactions

With both policies active you should see three different outcomes:

| Amount | Expected outcome    | Why                                                        |
| ------ | ------------------- | ---------------------------------------------------------- |
| `5`    | `APPROVED`          | Under both thresholds                                      |
| `12`   | `REQUIRES_APPROVAL` | Over the $10 approval threshold, under the $15 spend limit |
| `20`   | `DENIED`            | Over the \$15 spend limit                                  |

### Test 1. `$5` should be APPROVED

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5,
    "recipientAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "purpose": "Test - under all limits",
    "category": "TESTING"
  }'
```

Response: `"status": "APPROVED"`, `"currency": "pathUSD"`.

### Test 2. `$12` should REQUIRE\_APPROVAL

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12,
    "recipientAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "purpose": "Test - over approval threshold"
  }'
```

Response: `"status": "REQUIRES_APPROVAL"` with a violation referencing the approval threshold.

### Test 3. `$20` should be DENIED

```bash theme={null}
curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20,
    "recipientAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "purpose": "Test - over max amount"
  }'
```

Response: `"status": "DENIED"` with a violation referencing the spend limit.

## Step 8. Execute the approved payment

This step uses the `payments:execute` scope, which your standard SDK key already includes.

Capture the `requestId` from the approved request instead of copy-pasting it. Approved requests
expire after 5 minutes, so re-requesting like this always gives you a fresh id. This re-runs
Test 1 and saves the id with `jq`:

```bash theme={null}
REQUEST_ID=$(curl -s -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5, "recipientAddress": "0x1234567890abcdef1234567890abcdef12345678", "purpose": "Test - under all limits"}' \
  | jq -r '.requestId')
```

Then execute it:

```bash theme={null}
curl -X POST "https://conto.finance/api/sdk/payments/$REQUEST_ID/execute" \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

The response includes:

* `txHash`. Onchain transaction hash on Tempo Testnet.
* `explorerUrl`. Link to view on [`explore.testnet.tempo.xyz`](https://explore.testnet.tempo.xyz).

## Step 9. Same flow via the SDK

```typescript theme={null}
import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY });

// Test 1
const test1 = await conto.payments.request({
  amount: 5,
  recipientAddress: '0x1234567890abcdef1234567890abcdef12345678',
  purpose: 'Test - under all limits',
});
console.log('Test 1:', test1.status); // APPROVED

if (test1.status === 'APPROVED') {
  const result = await conto.payments.execute(test1.requestId);
  console.log('TX hash:', result.txHash);
  console.log('Explorer:', result.explorerUrl);
}

// Test 2
const test2 = await conto.payments.request({
  amount: 12,
  recipientAddress: '0x1234567890abcdef1234567890abcdef12345678',
  purpose: 'Test - over approval threshold',
});
console.log('Test 2:', test2.status); // REQUIRES_APPROVAL

// Test 3
const test3 = await conto.payments.request({
  amount: 20,
  recipientAddress: '0x1234567890abcdef1234567890abcdef12345678',
  purpose: 'Test - over max amount',
});
console.log('Test 3:', test3.status); // DENIED
```

For one-call `request + execute`, set `autoExecute: true` on the request. The response comes back with status `EXECUTED` and an `execution` object carrying `txHash` and `explorerUrl`. It works with any key that has `payments:execute`, which the standard preset includes.

## Verify in the dashboard

After Step 8:

1. Dashboard > **Transactions**. The transaction shows `Confirmed`; open it to see the network (Tempo Testnet) and the explorer link.
2. Click the explorer link to verify onchain.
3. **Analytics > Audit Trail** tab. See the full policy evaluation trail.

<Check>You've verified policy enforcement and made a real onchain payment on Tempo Testnet.</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Expected a block after setting per-transaction limit to 0">
    Wallet-level per-transaction limit `0` means unlimited. Edit the wallet limits on the agent
    detail page and set a positive cap, or suspend the agent if all payments should stop.
  </Accordion>

  <Accordion title="Payment denied but expected REQUIRES_APPROVAL">
    Policies combine with AND logic. If one policy denies while another requires approval, the
    denial wins. Check the **Permissions** tab for every assigned policy.
  </Accordion>

  <Accordion title="INSUFFICIENT_BALANCE">
    The testnet wallet needs funding. On the wallet card, click **Fund Wallet > Request Testnet
    Tokens**.
  </Accordion>

  <Accordion title="AUTH_FAILED">
    Invalid or expired SDK key. Generate a new one from the agent detail page.
  </Accordion>
</AccordionGroup>

## Moving to production

Once the testnet flow works:

1. Create a production wallet on **Tempo Mainnet** (`USDC.e`), **Base** (`USDC`), or **Solana** (`USDC`).
2. Fund it with real stablecoins.
3. Link the production wallet to your agent with production-sized limits.
4. Update or create production policies. The test policies can remain for reference.

Your SDK integration code does not change. Only the wallet and chain change.

## Next steps

<CardGroup cols={2}>
  <Card title="Agent sandbox quickstart" icon="robot" href="/quickstart/agent-sandbox">
    Let an autonomous agent create a test-mode sandbox without human signup
  </Card>

  <Card title="Connect your framework" icon="plug" href="/quickstart/connecting-agents">
    OpenAI, Claude, LangChain, Python integration snippets
  </Card>

  <Card title="SDK payments reference" icon="code" href="/sdk/payments">
    Full method signatures, options, error model
  </Card>

  <Card title="Policy overview" icon="shield" href="/policies/overview">
    Every policy type and rule type
  </Card>

  <Card title="Defaults" icon="gear" href="/reference/defaults">
    Every default value in one place
  </Card>
</CardGroup>