Counterparties API

Manage payment recipients and trust levels.

List Counterparties

curl https://conto.finance/api/counterparties \
  -H "Authorization: Bearer $CONTO_API_KEY"

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Results per page
`offset`	number	0	Pagination offset
`status`	string	all	`TRUSTED`, `VERIFIED`, `UNKNOWN`, `BLOCKED`
`search`	string	-	Search by name or address

Response

{
  "counterparties": [
    {
      "id": "cpty_abc123",
      "name": "OpenAI",
      "address": "0x892c45Dd7745D0643036b4c955Ac8e6706g...",
      "status": "TRUSTED",
      "trustScore": 95,
      "category": "API_PROVIDER",
      "transactionCount": 150,
      "totalVolume": 7500.00,
      "lastTransactionAt": "2024-01-15T14:30:00Z",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Counterparty

curl https://conto.finance/api/counterparties/{counterpartyId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "id": "cpty_abc123",
  "name": "OpenAI",
  "address": "0x892c45Dd7745D0643036b4c955Ac8e6706g...",
  "status": "TRUSTED",
  "trustScore": 95,
  "category": "API_PROVIDER",
  "notes": "Primary AI provider for customer support agents",
  "website": "https://openai.com",
  "transactionCount": 150,
  "totalVolume": 7500.00,
  "averageAmount": 50.00,
  "lastTransactionAt": "2024-01-15T14:30:00Z",
  "networkTrust": {
    "globalScore": 98,
    "transactionCount": 50000,
    "organizationCount": 250,
    "lastUpdated": "2024-01-15T00:00:00Z"
  },
  "createdAt": "2024-01-01T10:00:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Create Counterparty

curl -X POST https://conto.finance/api/counterparties \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Anthropic",
    "address": "0x123abc...",
    "category": "API_PROVIDER",
    "status": "VERIFIED",
    "notes": "Claude API provider"
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Counterparty name
`address`	string	Yes	Wallet address
`category`	string	No	Merchant category
`status`	string	No	Trust status
`notes`	string	No	Internal notes
`website`	string	No	Website URL

Status Values

Status	Description
`TRUSTED`	Fully trusted, no restrictions
`VERIFIED`	Identity verified
`UNKNOWN`	Not yet verified
`BLOCKED`	All payments blocked

Category	Description
`API_PROVIDER`	API service providers
`CLOUD_SERVICES`	Cloud infrastructure
`DATA_SERVICES`	Data providers
`TOOLS`	Software tools
`VENDOR`	General vendors
`CONTRACTOR`	Service contractors
`REFUND`	Customer refunds
`OTHER`	Other categories

Update Counterparty

curl -X PUT https://conto.finance/api/counterparties/{counterpartyId} \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "status": "TRUSTED",
    "notes": "Updated notes"
  }'

Update Trust Status

Trust Counterparty

curl -X POST https://conto.finance/api/counterparties/{counterpartyId}/trust \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{"reason": "Verified business relationship"}'

Block Counterparty

Blocking a counterparty will prevent all future payments to this address.

curl -X POST https://conto.finance/api/counterparties/{counterpartyId}/block \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{"reason": "Suspicious activity"}'

Unblock Counterparty

curl -X POST https://conto.finance/api/counterparties/{counterpartyId}/unblock \
  -H "Authorization: Bearer $CONTO_API_KEY"

Lookup by Address

Find a counterparty by wallet address.

curl "https://conto.finance/api/counterparties/lookup?address=0x..." \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "found": true,
  "counterparty": {
    "id": "cpty_abc123",
    "name": "OpenAI",
    "address": "0x...",
    "status": "TRUSTED",
    "trustScore": 95
  },
  "networkTrust": {
    "globalScore": 98,
    "transactionCount": 50000,
    "status": "TRUSTED"
  }
}

Transaction History

Get transactions with a specific counterparty.

curl "https://conto.finance/api/counterparties/{counterpartyId}/transactions?limit=50" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "transactions": [
    {
      "id": "tx_abc123",
      "amount": 50.00,
      "currency": "USD",
      "status": "CONFIRMED",
      "agentId": "agt_xyz789",
      "agentName": "Support Agent",
      "purpose": "API credits",
      "createdAt": "2024-01-15T14:30:00Z"
    }
  ],
  "summary": {
    "totalVolume": 7500.00,
    "transactionCount": 150,
    "averageAmount": 50.00
  },
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Network Trust Data

Get network-wide trust intelligence for an address.

curl "https://conto.finance/api/counterparties/network-trust?address=0x..." \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "address": "0x...",
  "networkTrust": {
    "globalScore": 98,
    "transactionCount": 50000,
    "organizationCount": 250,
    "successRate": 99.9,
    "averageAmount": 75.00,
    "firstSeen": "2023-01-15T00:00:00Z",
    "lastSeen": "2024-01-15T14:30:00Z",
    "status": "TRUSTED",
    "flags": []
  },
  "riskIndicators": {
    "ofacMatch": false,
    "highRiskCountry": false,
    "unusualPattern": false
  }
}

Bulk Import

Import multiple counterparties at once.

curl -X POST https://conto.finance/api/counterparties/import \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparties": [
      {
        "name": "Vendor A",
        "address": "0x...",
        "category": "VENDOR",
        "status": "VERIFIED"
      },
      {
        "name": "Vendor B",
        "address": "0x...",
        "category": "VENDOR",
        "status": "VERIFIED"
      }
    ]
  }'

Response

{
  "imported": 2,
  "skipped": 0,
  "errors": [],
  "counterparties": [
    { "id": "cpty_abc123", "name": "Vendor A" },
    { "id": "cpty_def456", "name": "Vendor B" }
  ]
}

SDK: Create Counterparty (Agent Endpoint)

Agents can programmatically create or update counterparties via the SDK endpoint. This upserts on [organizationId, address] and automatically creates an AgentRelationship. Required Scope: counterparties:write

curl -X POST https://conto.finance/api/sdk/counterparties \
  -H "Authorization: Bearer conto_agent_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Anthropic",
    "address": "0x123abc...",
    "type": "VENDOR",
    "category": "AI_SERVICES",
    "description": "Claude API provider"
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Counterparty name (1-200 chars)
`address`	string	Yes	Wallet address (1-200 chars)
`type`	string	No	Counterparty type (default: `VENDOR`)
`category`	string	No	Spending category
`description`	string	No	Notes (max 500 chars)

Response

{
  "id": "cpty_abc123",
  "name": "Anthropic",
  "address": "0x123abc...",
  "type": "VENDOR",
  "category": "AI_SERVICES",
  "trustScore": 0.2,
  "trustLevel": "LOW",
  "riskLevel": "MEDIUM",
  "created": true
}

If the address already exists for the organization, existing fields are updated and created still returns true. An AgentRelationship (TRANSACTS_WITH) is automatically created if it doesn’t exist. New counterparties start with a LOW trust level (score 0.2).

Delete Counterparty

curl -X DELETE https://conto.finance/api/counterparties/{counterpartyId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Deleting a counterparty does not delete transaction history. The counterparty will be recreated if a new transaction is made to the same address.

Error Responses

Status	Code	Description
400	`INVALID_INPUT`	Invalid request data
400	`INVALID_ADDRESS`	Invalid wallet address
401	`AUTH_FAILED`	Authentication failed
403	`INSUFFICIENT_SCOPE`	Missing required scope
404	`NOT_FOUND`	Counterparty not found
409	`ALREADY_EXISTS`	Address already registered

API Reference

Counterparties

Counterparties API

List Counterparties

Query Parameters

Response

Get Counterparty

Response

Create Counterparty

Request Body

Status Values

Categories

Update Counterparty

Update Trust Status

Trust Counterparty

Block Counterparty

Unblock Counterparty

Lookup by Address

Response

Transaction History

Response

Network Trust Data

Response

Bulk Import

Response

SDK: Create Counterparty (Agent Endpoint)

Request Body

Response

Delete Counterparty

Error Responses

API Reference

​Counterparties API

​List Counterparties

​Query Parameters

​Response

​Get Counterparty

​Response

​Create Counterparty

​Request Body

​Status Values

​Categories

​Update Counterparty

​Update Trust Status

​Trust Counterparty

​Block Counterparty

​Unblock Counterparty

​Lookup by Address

​Response

​Transaction History

​Response

​Network Trust Data

​Response

​Bulk Import

​Response

​SDK: Create Counterparty (Agent Endpoint)

​Request Body

​Response

​Delete Counterparty

​Error Responses

Counterparties API

List Counterparties

Query Parameters

Response

Get Counterparty

Response

Create Counterparty

Request Body

Status Values

Categories

Update Counterparty

Update Trust Status

Trust Counterparty

Block Counterparty

Unblock Counterparty

Lookup by Address

Response

Transaction History

Response

Network Trust Data

Response

Bulk Import

Response

SDK: Create Counterparty (Agent Endpoint)

Request Body

Response

Delete Counterparty

Error Responses