Manage counterparties and vendors

API Documentation

A counterparty is a person or business your organization pays, such as a vendor. To send money, you'll need a counterparty with accurate payment details.

Each counterparty has one or more rails, and a rail is either a bank account or a wallet address. Agents send to a rail, so they need the rail's ID (cpr_...). A counterparty's own ID starts with cp_.

Ways to add a counterparty

There are three ways to add a counterparty:

Method	How it works
Enter the details	You enter the payment details yourself in the console.
Agent creates it	The agent creates the counterparty, if its policy allows. The creation is an intent, so it may need approval.
Request details	We email the counterparty a secure form. You do not see their full payment information, and you can pay them once they submit it.

Find an existing counterparty

Before you create a counterparty for a wallet address, we recommend checking whether the address is already saved:

Shell

catena counterparties list
catena counterparties list --address 0x... --network base

If there is a match, the command will return the full counterparty. Use the rails[].id whose walletAddress matches.

Note that an agent only sees the counterparties its policy allows. An empty list means the agent can see no counterparty with that rail.

Create a counterparty

You can create a counterparty with bank details, with a wallet, or with only an email address.

With bank details:

Shell

catena counterparties create bank --name "Acme Supplies" \
  --bank-name "$BANK_NAME" --routing-number "$ROUTING_NUMBER" --account-number "$ACCOUNT_NUMBER" \
  --address-street "1 Main St" --address-city "New York" \
  --address-state NY --address-postal-code 10001

With a wallet:

Shell

catena counterparties create wallet --name "Acme Supplies" \
  --address 0x... --network base

A wallet rail is for one network and one stablecoin. You can pass --network base or --network arc, and the rail takes USDC unless you pass --asset (e.g., --asset ousd for OUSD on Base). catena setup-state lists the other stablecoins your organization holds, under organization.heldAssets.

With only an email (when you do not have payment details yet):

Shell

catena counterparties create --name "Acme Supplies" --email billing@acme.example

An email-only counterparty has status: "awaiting_details" and no rails, so it cannot receive a payment yet. Creating it sends no email.

Each form returns an intent. When .status is completed, the counterparty is on .data.counterparty (and for the bank and wallet forms, the new rail's ID is in rails[].id). If the creation needs approval, its status will be pending.

Request payment details

If a counterparty has an email but no usable rail, you can ask them for their payment details:

Shell

catena counterparties request-details cp_... --bank
catena counterparties request-details cp_... --wallet

Pass --bank, --wallet, or both. The agent's policy applies to the request, so it may need approval. The command returns before the counterparty answers, so we recommend running counterparties list again after they submit.

Paying a new counterparty

Approving a new counterparty adds it to your organization. However, an agent can only pay it when the counterparty is on the Send capability's list in the agent's policy. See Policies for details.