Settlement API integration guide

The Atlas settlement network supports four core settlement workflows. Atlas Plus organizations have access to all workflows; standard Atlas organizations can perform withdrawal to a trusted counterparty and one-way settlements.

Settlement workflow	Atlas	Atlas Plus
Withdrawal to trusted counterparty	✔	✔
Send funds (one-way)	✔	✔
Receive funds (one-way)	✔	✔
Send and receive (two-way)	—	✔

USD is supported across all Atlas settlement workflows (UI and API). USD is treated as another asset within a wallet for the purposes of settlement. No network fees apply for USD settlement legs.

Prerequisites

Before integrating with the Atlas settlement network API, complete the following setup steps in the Anchorage Digital web dashboard:

Create your API key permission group and API key. See API keys and Permission groups.
Create a Shared API key.
Set up and configure your participant vault. See Your participants in the web dashboard under Directory.
Collect trusted counterparty IDs from all counterparties you will be transacting with.

Atlas endpoints

Endpoint	Required permissions	Overview	Notes
Propose a settlement	Propose and accept settlements	Propose a settlement with a counterparty for assets coming from and/or arriving into wallets owned by your participant.	Positive amounts indicate funds to be received; negative amounts indicate funds to be sent.
Authorize a settlement	Authorize settlements	After proposing or accepting a settlement, the settlement details must be authorized.	To authorize via API, the API key must have the `Authorize settlement` permission. Otherwise, authorization takes place in the app according to organization policy.
Accept a settlement	Propose and accept settlements	Accept a proposed settlement and select wallets to receive funds to and/or send funds from.	Use positive numbers for assets to receive and negative for assets to send. The sum of amounts, by asset type, must exactly match the negative of the proposer’s amounts. The special string `createWallet` can be used to create a new wallet for this asset.
Reject a proposed settlement	Propose and accept settlements	Reject a settlement proposed to your participant, or cancel the authorization of a settlement you have already accepted. Proposed settlements that have been authorized by both parties (`Executing` or `Executed` state) cannot be canceled.	To reject an authorization via API, the API key must have the `Authorize settlement` permission.
List settlements	Read vault activity	Get settlements proposed by you or proposed to you.
Get settlement by ID	Read vault activity	Get a single settlement by its ID.
Get counterparty details by ID	Read vault activity	List details about a specific counterparty.
List my trusted counterparties	Read vault activity	List all trusted counterparties.
Get participant by ID	Read vault activity	Get a single participant by its ID.
List participants	Read vault activity	Get the list of participants you have access to.

The createWallet string is only available for the Accept a settlement endpoint. It indicates that a new wallet should be created for the specified asset during the settlement.

Critical IDs

ID	Details
`participantId`	The ID associated with your participant account. Counterparties use this ID to find you and initiate settlements. Your participant name is visible to other network participants when they search by participant ID — contact your client experience manager to use a different display name.
`proposerId`	The participant ID of whoever proposed the settlement.
`acceptorId`	The participant ID of whoever is accepting the settlement.
`settlementId`	The unique ID associated with each settlement. Used to query settlements via API.
`idempotentId`	See the idempotency section in the API documentation.
`clientReferenceId`	A unique ID created by the proposing client. Can be any alphanumeric string.
`vaultId`	The vault ID of the sending party. Use List Vaults to retrieve.
`walletId`	The wallet ID of the sending party. Use List Wallets to retrieve.

Getting started

1. API permission group

Set up an API permission group for Atlas settlement operations. See Permission groups for general setup instructions. Recommended permissions:

	Global (org-wide)	Vault-level
Required	N/A	`Read`, `Propose and Accept Settlements`, `Authorize Settlements`
Optional	`Initiate withdrawal` — enables the withdrawal API with a Trusted Counterparty as the destination	`Create address` — enables creating a new wallet using the same API key; `Transfer funds` — enables funding sending vaults for settlement via API

2. API key

Create an API key using the permission group above. See API keys for details, including how to generate an Ed25519 key pair.

3. Participant vault setup

Set up and configure your participant vault under Your participants in the web dashboard.

4. Wallet balance and transaction information

Before testing settlement APIs, fetch your settlement wallet details to identify balance and walletId values required for settlement.

List wallets or Get wallet by ID — returns all wallets accessible to the API key, including balance details.
List transactions — returns all on-chain transfers, including outgoing settlement activity and incoming deposits.

5. Trusted counterparty IDs

Collect participantId values from all counterparties you will be sending to or receiving from. Counterparties must share their participant IDs with you directly.

Quorum or authorization required?

Settlement	Initiator org	Acceptor org
Send	Quorum approval once initiated	Accept only
Receive	Quorum approval once initiated	Accept + quorum approval
Two-way	Quorum approval once initiated; accept and quorum approve to send	Accept and quorum approve to send

Settlement workflows

Conditions for settlement

Before Anchorage Digital holds and moves funds for settlement, the following conditions must be met. One-way settlement

The proposer has authorized the proposed settlement.
The proposer has sufficient funds for the settlement amount.
The proposer has sufficient funds to cover on-chain network fees.

Two-way settlement

The proposer has authorized the proposed settlement.
The proposer has sufficient funds for the settlement amount.
The proposer has sufficient funds to cover on-chain network fees.
The acceptor has accepted and authorized the proposed settlement.
The acceptor has sufficient funds for the settlement amount.
The acceptor has sufficient funds to cover on-chain network fees.

One-way settle (send funds)

(Proposer) Collect the recipient participantId and configure participant vault details.
(Proposer) Call Propose a settlement. Use negative amounts for assets being sent; positive for assets being received. Amounts exclude fees.
(Proposer) Call Authorize settlement (or authorize via the web dashboard).
(Acceptor) Poll List settlements to detect pending settlement actions.
(Acceptor) Call Accept settlement (or accept via the web dashboard).
- Select vault and wallet IDs for your side of the settlement.
- Invert the amounts from the List settlements response. The sum of amounts, by asset type, must be exactly opposite the proposer’s amounts.
- Use createWallet to create a new wallet for an asset if needed.
(Acceptor) Confirm receipt via List transactions (type: Deposit).
(Proposer and acceptor) Verify final state via List settlements.

One-way settle (receive funds)

(Proposer) Collect the recipient participantId and configure participant vault details.
(Proposer) Call Propose a settlement. Use positive amounts for assets being received; negative for assets being sent. Amounts exclude fees.
(Proposer) Call Authorize settlement (or authorize via the web dashboard).
(Acceptor) Collect the recipient participantId and configure participant vault details.
(Acceptor) Poll List settlements to detect pending settlement actions.
(Acceptor) Call Accept settlement (or accept via the web dashboard).
- Select vault and wallet IDs for your side of the settlement.
- Invert the amounts from the List settlements response.
- Use createWallet to create a new wallet for an asset if needed.
(Acceptor) Call Authorize settlement (or authorize via the web dashboard). Settlement transfer initiates once all conditions are satisfied.
(Proposer) Confirm receipt via List transactions (type: Deposit).
(Proposer and acceptor) Verify final state via List settlements.

Two-way settle (send and receive funds)

For a two-way settlement to execute, all four conditions must be met: (1) proposer has authorized, (2) acceptor has accepted, (3) acceptor has authorized, and (4) both parties have fully funded all legs of the settlement, including network fees.

(Proposer) Collect the recipient participantId and configure participant vault details.
(Proposer) Call Propose a settlement. Use positive amounts for assets being received; negative for assets being sent. Amounts exclude fees.
(Proposer) Call Authorize settlement (or authorize via the web dashboard).
(Acceptor) Collect the recipient participantId and configure participant vault details.
(Acceptor) Poll List settlements to detect pending settlement actions.
(Acceptor) Call Accept settlement (or accept via the web dashboard).
- Select vault and wallet IDs for your side of the settlement.
- Invert the amounts from the List settlements response.
- Use createWallet to create a new wallet for an asset if needed.
(Acceptor) Call Authorize settlement (or authorize via the web dashboard). Settlement transfer initiates once all conditions are satisfied.
(Proposer) Confirm receipt via List transactions (type: Deposit).
(Proposer and acceptor) Verify final state via List settlements.

​Prerequisites

​Atlas endpoints

​Critical IDs

​Getting started

​1. API permission group

​2. API key

​3. Participant vault setup

​4. Wallet balance and transaction information

​5. Trusted counterparty IDs

​Quorum or authorization required?

​Settlement workflows

​Conditions for settlement

​One-way settle (send funds)

​One-way settle (receive funds)

​Two-way settle (send and receive funds)

Prerequisites

Atlas endpoints

Critical IDs

Getting started

1. API permission group

2. API key

3. Participant vault setup

4. Wallet balance and transaction information

5. Trusted counterparty IDs

Quorum or authorization required?

Settlement workflows

Conditions for settlement

One-way settle (send funds)

One-way settle (receive funds)

Two-way settle (send and receive funds)