Machine View
Quickstart
Source: https://conto.finance/docs/quickstart/setup
# Quickstart
> Create an account, connect an agent, fund a Tempo Testnet wallet, and make your first policy-checked payment. No real funds required.
- Human URL: https://conto.finance/docs/quickstart/setup
- Raw Markdown: https://conto.finance/docs/quickstart/setup.md
- Terminal view: https://conto.finance/ai/docs/quickstart/setup
Documentation group: Start
# 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
A Conto organization with your account
An AI agent connected in Conto
A Tempo Testnet wallet funded with pathUSD
Spending policies that approve, require approval, or deny payments
A verified test payment on Tempo Testnet
## 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
npx @conto_finance/create-conto-agent
```
For CI or autonomous agent runs, use the sandbox JSON mode:
```bash
npx @conto_finance/create-conto-agent --sandbox --json
```
Then verify the generated project and run its example:
```bash
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](https://conto.finance/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 manage 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.
## 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.
Info:
New human organizations start with two active starter guardrails: a `$25` per-transaction limit,
a `$100` daily limit, and approval for payments above `$10`. They are visible in **Policies** and
can be edited, deactivated, or deleted as you replace them with your own controls. Approval
requests initially route to the owner's email notification channel; you can change the channel
later in **Settings** > **Channels**.
## Step 2. Create and fund a 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) |
| Ownership | **Organization-controlled** when your owner key is configured; otherwise **Conto-managed** |
Conto assigns the onchain address as soon as the wallet is created and assigns the wallet to
your Conto organization. Privy protects the wallet key material. Organization-controlled
wallets give your customer-only owner quorum root and export authority while Conto remains a
signer after Conto policies and approvals. Conto-managed wallets do not provide customer
self-service export.
Organization Owners can later use the wallet menu's encrypted export flow. The customer signs
the export authorization outside Conto and decrypts the result with a separate HPKE recipient
key. See [Exporting Wallet Keys](https://conto.finance/guides/exporting-wallet-keys).
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.
On the wallet card, open the menu and click **Fund Wallet**, then **Request Testnet Tokens**.
Free testnet `pathUSD` arrives in seconds.
For smart-contract wallets or importing an existing external wallet (watch-only), see [Custody modes](https://conto.finance/guides/custody-modes).
## Step 3. Connect an agent
Sidebar > **Agents > Connect Agent**.
| 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.
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.
Active starter guardrails use assigned scope and are linked to new agents automatically. If
you keep them active, they remain part of the agent's effective controls even after you add
more policies. Organization-scope baselines also apply automatically, without a link.
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
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
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
Open the agent detail page. In the **Wallets** tab, click **Link Wallet** and pick the Tempo Testnet wallet.
Recommended for the quickstart:
| Setting | Value |
|---|---|
| Per Transaction | `50` |
| Daily Limit | `500` |
| Weekly Limit | `2000` |
| Monthly Limit | `5000` |
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.
Starter guardrails are assigned directly to new agents, so they can be stricter than the wallet
defaults shown above. For a new organization, the `$25` starter per-transaction limit and `$100`
daily limit still apply until you edit, unassign, or deactivate those starter policies. Any
organization-scope baseline remains mandatory until it is edited or deactivated.
Default limits, time windows, and other agent-wallet link defaults are listed on the [Defaults](https://conto.finance/reference/defaults) page.
## Step 5. Generate an SDK key
On the agent detail page, click the **SDK Integration** tab.
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.
The full key is shown once. Save it to your environment:
```bash
export CONTO_API_KEY="conto_agent_your_key_here"
```
For scopes and key types (`standard` vs `admin`), see [Authentication](https://conto.finance/sdk/authentication).
Verify the setup:
```bash
curl https://conto.finance/api/sdk/setup \
-H "Authorization: Bearer $CONTO_API_KEY"
```
You should see:
- the agent is available for payment calls
- the setup summary includes your Tempo Testnet wallet and 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
Sidebar > **Policies > Create Policy**.
| Field | Value |
|---|---|
| Policy Name | `Test Spend Limit` |
| Policy Type | `Spend Limit` |
| Description | Deny transactions over $15 |
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.
### Policy B: approval threshold
Sidebar > **Policies > Create Policy**.
| Field | Value |
|---|---|
| Policy Name | `Test Approval Threshold` |
| Policy Type | `Approval Threshold` |
| Description | Require approval for transactions over $10 |
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.
### 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
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
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 customer-facing reason explaining that approval
is needed.
### Test 3. `$20` should be DENIED
```bash
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 customer-facing reason explaining that a spending control
blocked the payment.
## 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
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
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
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.
You've verified policy enforcement and made a real onchain payment on Tempo Testnet.
## Troubleshooting
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.
Policies combine with AND logic. If one policy denies while another requires approval, the
denial wins. Check the **Permissions** tab for every assigned policy.
The testnet wallet needs funding. On the wallet card, click **Fund Wallet > Request Testnet
Tokens**.
Invalid or expired SDK key. Generate a new one from the agent detail page.
## 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
### Agent sandbox quickstart
Link: https://conto.finance/quickstart/agent-sandbox
Let an autonomous agent create a test-mode sandbox without human signup
### Connect your framework
Link: https://conto.finance/quickstart/connecting-agents
OpenAI, Claude, LangChain, Python integration snippets
### SDK payments reference
Link: https://conto.finance/sdk/payments
Full method signatures, options, error model
### Policy overview
Link: https://conto.finance/policies/overview
Every policy type and rule type
### Defaults
Link: https://conto.finance/reference/defaults
Every default value in one place