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.
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.
