Skip to main content
A counterparty is the bank account or wallet belonging to any recipient of money (customers, suppliers, employees, or your external bank accounts). Create one financial address per counterparty and reuse its counterparty_id for payouts. An individual or business with several destinations is represented by several counterparties.

Fiat

Save the recipient’s bank details and set entity_type to individual, business, sole_proprietor, or non_profit. Choose the financial address type for the currency and payment rail below.

Stablecoins (USDC)

A crypto counterparty is an external wallet that you own. Crypto flows are closed loop: every crypto counterparty must be a wallet of your own. Create it with is_self_owned: true; without it, creation returns 400. A newly created crypto counterparty starts in pending, and creating it starts verification; see Initial state. A crypto counterparty must be active to be used for payouts. You can add as many crypto counterparties as you need, one per wallet address and blockchain. A crypto counterparty that is not self-owned, such as a wallet saved as the sender of a deposit, can’t be activated or paid: activation returns 409 and a payout to it returns 400. To use the wallet, create it again with is_self_owned: true, or update it to is_self_owned: true and activate it. Either way, verification starts.
A deposit from a pending crypto counterparty does not wait for verification; it goes through the usual deposit checks. Deposits from rejected or blocked counterparties are held for review.

Lifecycle

The status field describes the counterparty’s lifecycle. Blocking is separate. A pending counterparty can become active or rejected. A pending crypto wallet you create moves forward when its verification completes. You move any other pending counterparty forward by activating it. An explicit review reset can return it to pending. Starting a new review of an active counterparty does not itself change its status; a later decision can reject it. Verification attempts and their progress are separate from status.

Initial state

These rules apply only when a new record is created. Returning an existing counterparty preserves its status, blocking and details, and does not emit another initial-state event. You cannot choose status in a create or update request. Creating a crypto wallet counterparty, through the API or the Dashboard, starts verification. The counterparty stays pending until the decision. A new wallet emits counterparty.pending on creation, then counterparty.active or counterparty.rejected when the decision is made. If the wallet already exists as a pending counterparty, for example a sender recorded from a deposit, creating it again makes it self-owned and starts verification unless one is already in progress. If the create request fails, retry it. The retry returns the same counterparty and starts verification.

Blocking and payment eligibility

blocked is independent of status: an active counterparty can be blocked. Blocking prevents payments to and from the counterparty; unblocking removes that restriction without activating a pending or rejected counterparty. Creating a payout to a blocked or rejected counterparty returns 409 with code conflict, on every account, and no payout is created. Check status and blocked before you create a payout. An account configured to require verified counterparties requires active for payouts. Other fiat accounts do not apply that status requirement. Every payout still has to satisfy the account policy, currency and rail requirements, required recipient details, and payment risk checks. active alone does not mean the destination is reachable over every rail or guarantee that a payment will succeed.

Lifecycle webhooks

New records emit their initial-state event. Subscribe to both pending and active events if you need to observe new counterparties; either event can also describe a later lifecycle change. Event payloads are snapshots, and delivery order is not guaranteed. Retrieve the counterparty when you need its current status and blocked values. See Webhooks.

Fields

Financial address types

Each address includes its type and the fields below. Bank addresses also include account_holder_name. account_type is checking or savings; some destination countries require it. SWIFT has additional name, address and country requirements; see Counterparty details. The financial address does not itself select a USD rail: specify ach, fedwire, or swift on the payout as appropriate.

Create and use

Create a counterparty with POST /v1/counterparties. Check its lifecycle and blocking, then pass the returned id as counterparty_id when creating a payout, alongside account_id, amount, and currency. Creation is idempotent on the financial address: repeated creation of the same destination does not create another counterparty. If the financial address already exists, the existing counterparty is returned unchanged and any other values in the request (name, physical_address, date_of_birth, phone, email, legal_id) are ignored; change them with update. Your business, and each of your account holders, holds one counterparty per financial address. Reuse the saved ID for later payouts. For incoming deposits, counterparty_id identifies the sender where the rail provides the sender’s account details. It can be null; inbound ACH deposits have no counterparty because the rail does not share the originator’s account number. A booked transaction carries counterparty_id when a counterparty was resolved, otherwise null. Its nullable counterparty object contains financial and physical address details; source links to the originating deposit, payout, return or conversion when available.

Counterparties of account holders

If you have account holders in an FBO program, you can manage their counterparties as well as your own. Pass account_holder_id on POST /v1/counterparties to create a counterparty for that holder. Omit it to create one for your business.
  • List: pass account_holder_id on GET /v1/counterparties to list one holder’s counterparties. Without it, the list contains only your business’s own counterparties. A cursor stays bound to the account_holder_id it was issued for; replaying it without that filter returns 400.
  • Retrieve, update and activate: use the counterparty id alone. These endpoints take no account_holder_id.
  • Unknown holder: an account_holder_id that is not one of your account holders returns 404.
  • Deduplication: creation is idempotent on the financial address per owner, so your business and each account holder can each hold a counterparty for the same destination.
  • Webhooks: lifecycle webhooks are sent for your account holders’ counterparties as well as your own, to your business’s webhook endpoints. Use account_holder_id in the payload to tell them apart: it names the holder, or is null for your business’s own counterparties.
  • Sandbox: pass a holder’s counterparty as counterparty_id to simulate a deposit from it, or reject its verification. Another business’s counterparty returns 404.

Update

Update a counterparty with POST /v1/counterparties/{id}. You can change name, physical_address, date_of_birth, phone, email, legal_id, entity_type, and is_self_owned. Omitted fields stay unchanged; send null to clear the name, physical address, date of birth, phone, email or legal ID. Setting is_self_owned to false on a crypto counterparty that is self-owned returns 400. You can also add counterparties in the Dashboard, with an optional account type, and edit their name, legal ID, phone, email, and other details there; see Dashboard. The Dashboard also lets you add and manage counterparties for your account holders; through the API, see Counterparties of account holders. financial_address is immutable: create a new counterparty for changed bank details or a different wallet. The update endpoint does not accept metadata, status, or blocked. Updating details does not activate or unblock a counterparty.

Activate

Activate a counterparty with POST /v1/counterparties/{id}/activate while it is pending. The response is the counterparty. What happens depends on its financial address: Activating an active counterparty returns it unchanged. A rejected counterparty returns 409; contact your Augustus account manager to request a new review. Activation does not change blocked: a blocked counterparty stays blocked. Use it for senders Augustus saved as pending from incoming deposits. Crypto wallets you create don’t need it, because creating them starts verification. On accounts that require verified counterparties, payouts need the counterparty to be active; see Blocking and payment eligibility. In the Dashboard, Approve in a pending counterparty’s details does the same; Owners, Admins, and Editors can use it. A pending wallet whose ownership is External shows no Approve until you set its ownership to Own account.

Idempotency

Every POST endpoint requires an Idempotency-Key. Reuse the same key and identical body when retrying a request to receive the cached response. Reusing the key with a different body returns 409. This retry protection is separate from deduplication by financial address. See Idempotency.

List, retrieve and scopes

  • List counterparties: GET /v1/counterparties, with cursor pagination in both directions. limit accepts 1–100 and defaults to 10; pass next_cursor as cursor for older records or previous_cursor for newer ones. See Pagination. Pass status (pending, active, or rejected) to list only counterparties in that state; without it, the list includes every status.
  • Retrieve a counterparty: GET /v1/counterparties/{id}.
  • counterparties:read covers list and retrieve. counterparties:write covers create, update and activate. See Scopes.