# Manage counterparties and vendors

[API Documentation](https://docs.catena.com/api/list-counterparties.md)

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](https://docs.catena.com/intents.md), 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:

```sh
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](https://docs.catena.com/policies.md#counterparty-access) 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:

```sh
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:

```sh
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):

```sh
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:

```sh
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](https://docs.catena.com/policies.md#counterparty-access) for details.

## Related

- [Set policies](https://docs.catena.com/policies.md): Decide what each agent can do with its policy, from the accounts it can read and the counterparties it can pay to its spending rules and temporary overrides.
- [Pay a vendor invoice](https://docs.catena.com/recipes/pay-a-vendor-invoice.md): Your agent pays a vendor invoice by ACH, and any invoice at or above your approval threshold will wait for an admin.
- [List counterparties](https://docs.catena.com/api/list-counterparties.md): List counterparties visible to the agent.