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

# Counterparty Policies

> Control spending based on recipient trust

# Counterparty Policies

Counterparty policies control which recipients agents can pay based on trust levels, verification status, and relationships.

## Configuration (API)

Create counterparty rules via the Policy Rules API:

```bash theme={null}
curl -X POST https://conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "rules": [
      {
        "ruleType": "ALLOWED_COUNTERPARTIES",
        "operator": "IN_LIST",
        "value": "[\"0x1234567890abcdef1234567890abcdef12345678\", \"0xabcdef1234567890abcdef1234567890abcdef12\"]",
        "action": "ALLOW"
      },
      {
        "ruleType": "TRUST_SCORE",
        "operator": "GTE",
        "value": "0.7",
        "action": "ALLOW"
      }
    ]
  }'
```

## Rule Types

### ALLOWED\_COUNTERPARTIES

Only allow payments to specific wallet addresses (allowlist):

```json theme={null}
{
  "ruleType": "ALLOWED_COUNTERPARTIES",
  "operator": "IN_LIST",
  "value": "[\"0x1234...\", \"0x5678...\"]",
  "action": "ALLOW"
}
```

Address matching is **case-insensitive**.

### BLOCKED\_COUNTERPARTIES

Block payments to specific addresses:

```json theme={null}
{
  "ruleType": "BLOCKED_COUNTERPARTIES",
  "operator": "IN_LIST",
  "value": "[\"0xdead...\"]",
  "action": "DENY"
}
```

### TRUST\_SCORE

Only allow payments to counterparties above a trust threshold:

```json theme={null}
{
  "ruleType": "TRUST_SCORE",
  "operator": "GTE",
  "value": "0.7",
  "action": "ALLOW"
}
```

Trust scores are calculated automatically based on:

* Transaction history (30%)
* Reliability/success rate (30%)
* Account activity (20%)
* Verification status (20%), includes [external providers](/integrations/trust-providers) like Fairscale (Solana) and sanctions screening

<Info>
  The trust score and trust level are automatically fetched during policy evaluation and passed into the rule engine. You don't need to provide them in the payment request, just create the rules and the evaluator populates the context from the counterparty relationship and network trust service.
</Info>

### COUNTERPARTY\_STATUS

Require a specific trust level:

```json theme={null}
{
  "ruleType": "COUNTERPARTY_STATUS",
  "operator": "EQUALS",
  "value": "{\"status\": \"TRUSTED\"}",
  "action": "ALLOW"
}
```

## Trust Levels

| Level      | Score Range | Description                           |
| ---------- | ----------- | ------------------------------------- |
| `TRUSTED`  | 0.75-1.00   | High confidence, minimal restrictions |
| `VERIFIED` | 0.50-0.74   | Established relationship              |
| `UNKNOWN`  | 0.20-0.49   | Limited history                       |
| `BLOCKED`  | 0.00-0.19   | Blocked from transactions             |

## Whitelist Policy

For maximum control, use `ALLOWED_COUNTERPARTIES` with `ALLOW` action to only allow specific addresses. Any recipient not in the list will be denied:

```json theme={null}
{
  "ruleType": "ALLOWED_COUNTERPARTIES",
  "operator": "IN_LIST",
  "value": "[\"0x1234567890abcdef1234567890abcdef12345678\", \"0xabcdef1234567890abcdef1234567890abcdef12\"]",
  "action": "ALLOW"
}
```

## Relationship Spend Limits

In addition to policy rules, you can set per-counterparty spend limits on the `AgentRelationship` record. These are enforced automatically during payment evaluation:

| Field               | Description                                         |
| ------------------- | --------------------------------------------------- |
| `spendLimitPerTx`   | Maximum amount per transaction to this counterparty |
| `spendLimitDaily`   | Maximum total spend per day to this counterparty    |
| `spendLimitMonthly` | Maximum total spend per month to this counterparty  |

These limits are checked after the trust/block check and before the final approval decision. If a counterparty has a \$500/day limit, the evaluator aggregates all confirmed/pending transactions to that address today and blocks if the new payment would exceed it.

```bash theme={null}
# Set per-counterparty limits when creating a relationship
curl -X POST https://conto.finance/api/relationships \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "agentId": "cmm59z8fj000l49h7bjqza11p",
    "counterpartyId": "cmm5f0cpt000l49h7gpvxf11p",
    "spendLimitPerTx": 200,
    "spendLimitDaily": 500,
    "spendLimitMonthly": 5000
  }'
```

## Managing Counterparties

### Add Counterparty

```bash theme={null}
curl -X POST https://conto.finance/api/counterparties \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "name": "Amazon Web Services",
    "type": "VENDOR",
    "address": "0x1234...",
    "domain": "aws.amazon.com",
    "category": "INFRASTRUCTURE",
    "trustLevel": "TRUSTED"
  }'
```

### Block Counterparty

```bash theme={null}
curl -X POST https://conto.finance/api/counterparties/{id}/status \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "status": "BLOCKED",
    "reason": "Suspicious activity detected"
  }'
```

## Network Intelligence & External Providers

Conto's Network Intelligence provides cross-organization trust signals:

* See if other organizations have flagged an address
* Benefit from collective fraud detection
* Automatic trust score adjustments

For Solana wallets, Conto also integrates with [Fairscale](https://fairscale.xyz) for onchain reputation scoring. Wallets with no existing network data are automatically enriched with Fairscale scores, and behavioral red flags generate network alerts.

See [Trust & Risk Providers](/integrations/trust-providers) for configuration and all available providers.

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

## Best Practices

<AccordionGroup>
  <Accordion title="Start with Known Vendors">
    Begin with a small list of trusted vendors:

    ```json theme={null}
    {
      "policyType": "WHITELIST",
      "rules": [{
        "addresses": ["0xaws...", "0xopenai...", "0xgcp..."]
      }]
    }
    ```
  </Accordion>

  <Accordion title="Gradually Expand Trust">
    As you verify new vendors, increase their trust level:

    1. New vendor: UNKNOWN (allowed within default spend limits, approval required on high network risk)
    2. After review: VERIFIED
    3. After history: TRUSTED
  </Accordion>

  <Accordion title="Monitor Trust Scores">
    Regularly review trust scores in the dashboard. Investigate any drops.
  </Accordion>
</AccordionGroup>