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

# Core Concepts

> Learn about agents, wallets, policies, transactions, counterparties, and trust scores in Conto

# Core Concepts

Before integrating with Conto, it's helpful to understand the key concepts and terminology.

## Agents

An **Agent** represents an AI agent connected to Conto. Each agent has:

* **Name** - Human-readable identifier
* **Type** - The agent framework (OpenAI, Claude, LangChain, Custom)
* **Public Key** - Unique cryptographic identifier
* **Status** - Active, Paused, Suspended, or Revoked
* **SDK Keys** - API keys for authentication

```typescript theme={null}
// Example agent configuration
{
  name: "Customer Support Agent",
  agentType: "OPENAI_ASSISTANT",
  publicKey: "0x1234...",
  status: "ACTIVE"
}
```

## Wallets

A **Wallet** holds stablecoins for agent payments. Wallets can be linked to multiple agents with different spend limits.

| Property      | Description                 |
| ------------- | --------------------------- |
| `address`     | Wallet address              |
| `balance`     | Current stablecoin balance  |
| `chainType`   | EVM or SOLANA               |
| `custodyType` | PRIVY, SPONGE, or EXTERNAL  |
| `status`      | ACTIVE, FROZEN, or ARCHIVED |

### Supported Chains

| Chain          | Chain ID         | Type   | Currency | Environment       |
| -------------- | ---------------- | ------ | -------- | ----------------- |
| Tempo Testnet  | `42431`          | EVM    | pathUSD  | Testnet (default) |
| Tempo Mainnet  | `4217`           | EVM    | USDC.e   | Production        |
| Base           | `8453`           | EVM    | USDC     | Production        |
| Base Sepolia   | `84532`          | EVM    | USDC     | Testnet           |
| Ethereum       | `1`              | EVM    | USDC     | Production        |
| Arbitrum One   | `42161`          | EVM    | USDC     | Production        |
| Polygon        | `137`            | EVM    | USDC     | Production        |
| Solana Mainnet | `solana-mainnet` | Solana | USDC     | Production        |
| Solana Devnet  | `solana-devnet`  | Solana | USDC     | Testnet           |

<Info>
  Tempo chains require no separate gas token. Tempo Testnet uses `pathUSD`; Tempo Mainnet uses
  `USDC.e`, making Tempo the easiest option for both testing and production.
</Info>

## Cards

A **Card** is a payment card (virtual or physical) that agents can use for traditional merchant payments. Today, Cards are registered manually for BYOC flows; native issuing through Conto is not yet generally available.

| Property          | Description                        |
| ----------------- | ---------------------------------- |
| `provider`        | STRIPE\_ISSUING, LITHIC, or MANUAL |
| `last4`           | Last 4 digits of card number       |
| `cardType`        | VIRTUAL or PHYSICAL                |
| `status`          | ACTIVE, PAUSED, or CANCELLED       |
| `spendLimitDaily` | Card-level daily limit             |

Cards are assigned to agents via **Agent-Card Links**, similar to wallet links. Each agent gets independent spend limits, time windows, and merchant category controls on the shared card. Policies can also be linked directly to cards for rule engine enforcement.

## Agent-Wallet Links

When you link an agent to a wallet, you configure:

* **Spend Limits** - Per-transaction, daily, weekly, monthly limits
* **Time Windows** - Allowed hours and days for transactions
* **Delegation Type** - Full, Limited, View-Only, Preapproved, or Allowlist access

```typescript theme={null}
// Example agent-wallet link (business-hours restriction)
{
  spendLimitPerTx: 500,      // Max $500 per transaction
  spendLimitDaily: 2000,     // Max $2,000 per day
  spendLimitMonthly: 20000,  // Max $20,000 per month
  allowedHoursStart: 9,      // 9 AM (default: 0)
  allowedHoursEnd: 17,       // 5 PM (default: 24)
  allowedDays: ["Mon", "Tue", "Wed", "Thu", "Fri"]  // default: all 7 days
}
```

## Policies

A **Policy** is a set of rules that determine whether a payment should be approved, denied, or require manual approval.

### Policy Types

<CardGroup cols={2}>
  <Card title="Spend Limit" icon="dollar-sign">
    Control maximum amounts per transaction, day, week, or month
  </Card>

  <Card title="Time Window" icon="clock">
    Restrict transactions to specific hours and days
  </Card>

  <Card title="Counterparty" icon="user-check">
    Control which recipients are allowed based on trust
  </Card>

  <Card title="Geographic" icon="globe">
    Block transactions to sanctioned countries (OFAC compliance)
  </Card>

  <Card title="Category" icon="tag">
    Allow or block specific spending categories
  </Card>

  <Card title="Approval Threshold" icon="check-circle">
    Require manual approval above certain amounts
  </Card>

  <Card title="Velocity" icon="gauge">
    Limit transaction frequency to prevent rapid drain
  </Card>

  <Card title="x402 / MPP" icon="bolt">
    Controls for micropayment protocols (price ceilings, service allowlists)
  </Card>
</CardGroup>

### Policy Priority

Policies are evaluated in priority order (highest first). This allows you to:

1. Evaluate critical security/compliance policies first (priority 90+)
2. Set default policies (priority 50) for normal operations
3. Add catch-all policies (priority 10) for fallbacks

Priority only controls order. Policies still combine with AND logic, so a high-priority allow rule
does not override a lower-priority deny or failed allowlist.

## Transactions

A **Transaction** represents a stablecoin payment from a wallet to a recipient.

### Transaction Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending: Request Created
    Pending --> Approved: Policy Passed
    Pending --> Denied: Policy Failed
    Pending --> RequiresApproval: Needs Human Review
    RequiresApproval --> Approved: Approved
    RequiresApproval --> Denied: Rejected
    Approved --> Executing: Execute Called
    Executing --> Completed: Tx Submitted
    Completed --> Confirmed: Block Confirmed
    Executing --> Failed: Tx Failed
    Confirmed --> [*]
    Denied --> [*]
    Failed --> [*]
```

### Transaction Properties

| Property       | Description                 |
| -------------- | --------------------------- |
| `txHash`       | Blockchain transaction hash |
| `amount`       | Payment amount              |
| `status`       | Current transaction status  |
| `policyResult` | Policy evaluation result    |
| `purpose`      | Reason for payment          |
| `category`     | Spending category           |

## Counterparties

A **Counterparty** is a recipient of payments (vendor, merchant, agent, service, or platform).

### Trust Levels

| Level        | Score Range | Description                                   |
| ------------ | ----------- | --------------------------------------------- |
| **TRUSTED**  | 75 - 100    | High confidence, minimal restrictions         |
| **VERIFIED** | 50 - 74     | Established relationship, standard monitoring |
| **UNKNOWN**  | 20 - 49     | New or limited history, requires scrutiny     |
| **BLOCKED**  | 0 - 19      | High risk, all transactions blocked           |

### Trust Score Factors

Trust scores are calculated based on:

* **History (30%)** - Transaction count and volume
* **Reliability (30%)** - Success rate, failed transactions
* **Activity (20%)** - Account age, recency, consistency
* **Verification (20%)** - Manual verification, network data, and [external trust providers](/integrations/trust-providers) (Fairscale for Solana, sanctions screening)

Conto maintains both a **per-organization** trust score (your org's own view of
a counterparty) and a **network** trust score (the cross-organization view).
Policies can reference either via the `TRUST_SCORE` rule type. See
[Trust Scoring](/guides/trust-scoring) for the full breakdown.

## Network Intelligence

Conto's **Network Intelligence** provides anonymized cross-organization trust data:

* See if other organizations have flagged an address
* Benefit from collective fraud detection
* Contribute to network safety (opt-in)

For **Solana wallets**, trust scores are powered by [Fairscale](https://fairscale.xyz), a composable reputation scoring system that analyzes onchain behavioral signals like transaction patterns, staking activity, and token holdings. Solana addresses with no existing network data are automatically enriched with Fairscale scores, so you get real trust data instead of blank defaults.

Conto also integrates with sanctions screening providers (Chainalysis, TRM Labs, and a built-in OFAC list) for compliance. See [Trust & Risk Providers](/integrations/trust-providers) for full details on all integrated providers.

<Note>
  Network Intelligence data is anonymized. Organizations share aggregate trust signals, not
  transaction details.
</Note>

## SDK Keys vs API Keys

Conto uses two types of authentication:

| Credential               | Format               | Scope                      | Typical use                                           |
| ------------------------ | -------------------- | -------------------------- | ----------------------------------------------------- |
| **Standard SDK key**     | `conto_agent_xxx...` | One agent                  | The payment lifecycle and agent-scoped reads          |
| **Admin SDK key**        | `conto_agent_xxx...` | One agent, elevated scopes | Delegated management of agents, wallets, and policies |
| **Organization API key** | `conto_xxx...`       | Whole organization         | Backend/admin automation with `ContoAdmin`            |

* **Standard SDK keys** cover the payment lifecycle (`payments:request`, `payments:execute`, `payments:approve`, `payments:confirm`) plus read-only agent data. Policies, spend limits, and approvals govern what those payments can do.
* **Admin SDK keys** add elevated `agents:write`, `wallets:write`, and `policies:write` scopes but remain tied to a specific agent identity.
* **Organization API keys** are the canonical credential for backend provisioning, integrations, and the `ContoAdmin` SDK.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart/setup">
    Set up your first agent
  </Card>

  <Card title="Policy Guide" icon="shield" href="/policies/overview">
    Configure spending policies
  </Card>
</CardGroup>