Counterparty Policies

# Counterparty Policies

> Control spending based on recipient trust

- Human URL: https://conto.finance/docs/policies/counterparties
- Raw Markdown: https://conto.finance/docs/policies/counterparties.md
- Terminal view: https://conto.finance/ai/docs/policies/counterparties

Documentation group: Products

# Counterparty Policies

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

## Configuration (API)

Create a complete `COUNTERPARTY` policy with its rules in one request:

```bash
curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trusted Counterparties",
    "policyType": "COUNTERPARTY",
    "priority": 50,
    "isActive": true,
    "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
{
  "ruleType": "ALLOWED_COUNTERPARTIES",
  "operator": "IN_LIST",
  "value": "[\"0x1234...\", \"0x5678...\"]",
  "action": "ALLOW"
}
```

Address matching is **case-insensitive**.

### BLOCKED_COUNTERPARTIES

Block payments to specific addresses:

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

### TRUST_SCORE

Only allow payments to counterparties above a trust threshold:

```json
{
  "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](https://conto.finance/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.

### COUNTERPARTY_STATUS

Require a specific trust level:

```json
{
  "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
{
  "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
# 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
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
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 shared counterparty risk signals
- 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](https://conto.finance/integrations/trust-providers) for configuration and all available providers.

Note:

  Network data is anonymized. Organizations share aggregate signals, not transaction details.

## Best Practices

    Begin with a small list of trusted vendors:

    ```json
    {
      "policyType": "WHITELIST",
      "rules": [{
        "addresses": ["0xaws...", "0xopenai...", "0xgcp..."]
      }]
    }
    ```

    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

    Regularly review trust scores in the dashboard. Investigate any drops.