Guides
  1. Atlas network

Settlement API Integration guide

Introduction

For all Web and iOS User Guide information see Atlas user guides.

There are currently 4 core settlement workflows supported under Atlas and Atlas Plus

Settlement workflowAtlasAtlas Plus
Withdrawal to trusted counterpartyYesYes
Send funds (one-way)YesYes
Receive funds (one-way)YesYes
Send and receive (two-way)NoYes
📘

USD Support on Atlas

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


Prerequisites and user guides

Please refer to our Atlas User Guide sections for more information regarding set up and prerequisites:



Atlas endpoints

EndpointRequired permissionsOverviewNotes
Propose a settlementPropose and accept settlementsPropose a settlement with a counterparty for a list of assets coming from and/or arriving into wallets owned by your participant.Positive amounts indicate funds to be received and negative amounts indicate funds to be sent.
Authorize a settlementAuthorize settlementsAfter your participant has proposed a settlement or accepted a settlement proposal, the details of the settlement 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 settlementPropose and accept settlementsAccept a proposed settlement and select wallets to receive funds to and/or send funds from.

Use positive numbers to describe assets to receive and negative to send. The sum of the amounts, by asset type, must match the negative of the sum of the amounts on the proposer's side of the settlement.

The special string createWallet can be used to indicate that a new wallet should be created for this asset for this settlement.

Reject a proposed settlementPropose and accept settlements

Rejects a settlement proposed to your network participant. Proposed settlements cannot be rejected if they have already been accepted.

After your participant has proposed a settlement or accepted a settlement proposal, the authorization of the settlement can be rejected, if needed.

To unauthorize a settlement via API, the API key must have the 'Authorize settlement' permission. Otherwise, rejecting the authorization takes place in the app according to organization policy.
List settlementsRead vault activityGet settlements proposed by you or proposed to you.
Get settlement by IDRead vault activityGet a single settlement by its ID.
Get counterparty details by IDRead vault activityList details about a specific counterparty.
List my trusted counterpartiesRead vault activityList all trusted counterparties.
Get participant by IDRead vault activityGet a single participant by its ID.
List participantsRead vault activityGet the list of participants you have access to.
📘

Rejecting a settlement

This endpoint can be used to either:

  1. Cancel a pending settlement you've initiated or authorized, but is still pending some sort of client action.
    1. To clarify, if the settlement has been authorized by both parties and all conditions have been met, the settlement is in Executing or Executed state and cannot be canceled.
  2. Reject a proposed settlement from another counterparty
📘

Use createWallet string when accepting a settlement (if needed)

The special string createWallet can be used to indicate that a new wallet should be created for this asset when accepting a settlement. This is only currently available for the 'Accept a settlement' endpoint.



Critical IDs

IDDetails
participantIdUnder “Your participants,” see the list of accounts participating in the network and their corresponding participant IDs. Other counterparties will use this ID to find you and initiate a settlement with you.
Note: Your participants’ name will be visible to other network participants when searching by your participant ID. If you wish to use a different name, such us your organization's name, contact your client experience manager.
proposerIdThis is the Participant ID of whoever proposed the settlement
acceptorIdThis is the Participant ID of whoever is accepting the settlement
settlementIdThe unique ID associated with each settlement, which can be used to query past settlements via API
idempotentIdSee idempotency section for more details
clientReferenceIdThis is a unique ID created by the proposing client that can be any alphanumeric string
vaultIdThe Vault ID of the sending party (use List Vaults)
walletIdThe Wallet ID of the Sending Party (use List Wallets)


Getting started

Prior to conducting settlement via API, you will need to complete the following steps:

  1. Create your own API key permission group
  2. Create your own API key
  3. Create a Shared API key
  4. Set up and configure your participant vault in the web dashboard
  5. Getting wallet balance and transaction tnformation
  6. Collect trusted counterparty IDs for which you will be sending and/or receiving funds

1) Client API permission group

After you have successfully signed up for the Atlas settlement network, Created the shared API key and established your settlement counterparty, you will need to set up your own API permission group and API key.

General permission group user guide

Recommended API permissions:

PermissionsGlobal (org-wide) permissionsVault-level permissions
RequiredN/ARead Propose and Accept Settlements Authorize Settlements
Optional
  • Initiate withdrawal: This enables you to leverage the quorum-required withdrawal API with your destination being a Trusted Counterparty rather than a specific address
  • Create address: This enables you to create a new wallet if needed to deposit funds into using the same API key. This permission is not as critical but it can help to enable all of these on the same key for ease of settlement - Transfer funds (transfers within Anchorage Digital): This enables you to fund the sending Vaults for settlement via API, if not funded already, but is not required for Atlas settlement purposes specifically

2. Client API Key

3. Set up and configure your participant vault in the web dashboard

4. Getting wallet balance and transaction information

Prior to testing our Atlas settlement APIs, you will need to fetch your settlement wallet details to identify balance and walletId details necessary for settlement.

5. Collect trusted counterparty IDs for which you will be sending and/or receiving funds

  • See "Trusted counterparties" page
  • Note: Your trusted counterparties will need sot share their participant ID with you


Quorum OR authorize settlement required?

SettlementInitiator orgAcceptor org
SendQuorum approval once initiatedAccept only
ReceiveQuorum approval once initiatedAccept + quorum approval
Two-wayQuorum approval once initiated
accept and quorum approve to send		Accept and quorum approve to send


Settlement workflows

See list of Atlas workflows above.

Conditions necessary for settlement

📘

Prior to Anchorage Digital holding and moving funds for the purposes of settlement, a few conditions must be met:

One-way settlement

  1. The proposer has authorized/ endorsed the proposed settlement
  2. The proposer has sufficient funds for the settlement amount
  3. The proposer has sufficient funds to cover on-chain network fees, in addition to the funds owed for the settlement

Two-way settlement

  1. The proposer has authorized/ endorsed the proposed settlement
  2. The proposer has sufficient funds for the settlement amount
  3. The proposer has sufficient funds to cover on-chain network fees, in addition to the funds owed for the settlement
  4. The acceptor has accepted and authorized/ endorsed the proposed settlement
  5. The acceptor has sufficient funds for the settlement amount
  6. The acceptor has sufficient funds to cover on-chain network fees, in addition to the funds owed for the settlement

1) One-way settle (send funds)



  1. (Proposer) Configure your participant vault details and and collect the necessary necessary recipient participantId needed for transfer of assets
  2. (Proposer) Propose a settlement (or web dashboard)
    1. The numeric value of this amount, excluding units. Use positive numbers for receiving and negative for sending assets. Amounts never include fees.
  3. (Proposer) Authorize settlement (or web dashboard)
  4. (Acceptor) Monitor List settlements to be notified when new settlement action is pending
  5. (Acceptor) Accept settlement (or web dashboard)
    1. Select vault and wallet IDs for your side of the settlement (sending and receiving)
    2. The numeric value of this amount, excluding units. Use positive numbers for receiving and negative for sending assets. Amounts never include fees.
    3. Invert the amounts seen in the list settlements response when submitting the accept settlement payload
    4. The set of wallets to use for the requested walletAmounts. The assets must match exactly the list of assets in the proposal and the amounts must be exactly opposite the amounts in the proposal. Use positive numbers to describe assets to receive and negative to send. The sum of the amounts, by asset type, must match the negative of the sum of the amounts on the proposer's side of the settlement.
    5. The special string createWallet can be used to indicate that a new wallet should be created for this asset for this settlement.
  6. (Acceptor) Receive funds into default vault wallets
    1. List transactions (Type = Deposit)
  7. (Proposer and acceptor) List ettlements

2) One-way settle (receive funds)



  1. (Proposer) Configure your participant vault details and and collect the necessary necessary recipient participantId needed for transfer of assets
  2. (Proposer) Propose a settlement (or web dashboard)
    1. The numeric value of this amount, excluding units. Use positive numbers for receiving and negative for sending assets. Amounts never include fees.
  3. (Proposer) Authorize settlement (or web dashboard)
  4. (Acceptor) Configure your participant vault details and and collect the necessary necessary recipient participantId needed for transfer of assets
  5. (Acceptor) Monitor List settlements to be notified when new settlement action is pending
  6. (Acceptor) Accept Settlement (or web dashboard)
    1. Select vault and wallet IDs for your side of the settlement (sending and receiving)
    2. The numeric value of this amount, excluding units. Use positive numbers for receiving and negative for sending assets. Amounts never include fees.
    3. Invert the amounts seen in the list dettlements response when submitting the accept settlement payload
    4. The set of wallets to use for the requested walletAmounts. The assets must match exactly the list of assets in the proposal and the amounts must be exactly opposite the amounts in the proposal. Use positive numbers to describe assets to receive and negative to send. The sum of the amounts, by asset type, must match the negative of the sum of the amounts on the proposer's side of the settlement.
    5. The special string createWallet can be used to indicate that a new wallet should be created for this asset for this settlement.
  7. (Acceptor) Authorize settlement (or web dashboard)
    1. Settlement transfer initiated at this time (assuming all settlement criteria are satisfied)
  8. (Proposer) Receive funds into default vault wallets
    1. List Transactions (Type = deposit)
  9. (Proposer and acceptor) List settlements

3) Two-way settle (Send and receive funds)


👍

Two-way settlement criteria

In order for a two-way settlement to occur, the following conditions must be met

  1. Proposer has authorized the settlement
  2. Acceptor has accepted the settlement
  3. Acceptor has authorized the settlement
  4. Both proposer and acceptor have fully funded all legs of the settlement (including network fees)
  1. (Proposer) Configure your participant vault details and and collect the necessary necessary recipient participantId needed for transfer of assets
  2. (Proposer) Propose a settlement (or web dashboard)
    1. The numeric value of this amount, excluding units. Use positive numbers for receiving and negative for sending assets. Amounts never include fees.
  3. (Proposer) Authorize settlement (or web dashboard)
  4. (Acceptor) Configure your participant vault details and and collect the necessary necessary recipient participantId needed for transfer of assets
  5. (Acceptor) Monitor List settlements to be notified when new settlement action is pending
  6. (Acceptor) Accept settlement (or web dashboard)
    1. Select vault and wallet IDs for your side of the settlement (sending and receiving)
    2. The numeric value of this amount, excluding units. Use positive numbers for receiving and negative for sending assets. Amounts never include fees.
    3. Invert the amounts seen in the list settlements response when submitting the accept settlement payload
    4. The set of wallets to use for the requested walletAmounts. The assets must match exactly the list of assets in the proposal and the amounts must be exactly opposite the amounts in the proposal. Use positive numbers to describe assets to receive and negative to send. The sum of the amounts, by asset type, must match the negative of the sum of the amounts on the proposer's side of the settlement.
    5. The special string createWallet can be used to indicate that a new wallet should be created for this asset for this settlement.
  7. (Acceptor) Authorize settlement (or web dashboard)
    1. Settlement transfer initiated at this time (assuming all settlement criteria are satisfied)
  8. (Proposer) Receive funds into default vault wallets
    1. List transactions (Type = Deposit)
  9. (Proposer and Acceptor) List settlements


Changelog

Please subscribe to our changelog for detailed updates across all Anchorage Digital APIs.

Updated 4 months ago

Did this page help you?