Add Counterparties

Overview

Grow your Go Network by listing your Go Account in a public directory along with other Go Accounts. Each enterprise in the directory has 1 listing for itself. An enterprise listing can have multiple entries. For example, your Go Account is an entry in your listing.

Find Go Accounts you want to connect with and add them as a counterparty for streamlined settlements and transactions. Counterparty connections are 1-to-1 relationships between two Go Accounts, enabling Settlements with one another.

Prerequisites

Get Started

1. List your Enterprise

List your enterprise in the public directory so that other enterprises can find you and add you as a counterparty.

Endpoint: Create Enterprise Listing

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export DESCRIPTION="<YOUR_PUBLIC_DESCRIPTION>"

curl -X POST \
  https://app.bitgo-test.com/api/address-book/v1/listing/global \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"description": "'"$DESCRIPTION"'"}'

import { BitGoAPI } from '@bitgo/sdk-api';
import { coins } from '@bitgo/sdk-core';
import { CreateAddressBookListingParams } from '@bitgo/sdk-core/dist/src/bitgo/address-book';
import * as dotenv from 'dotenv';

const OFC_WALLET_ID = process.env.OFC_WALLET_ID;

const bitgo = new BitGoAPI({
  accessToken: process.env.TESTNET_ACCESS_TOKEN,
  env: 'test',
  customRootURI: 'https://app.bitgo-test.com',
});

const coin = 'ofc';
bitgo.register(coin, coins.Ofc.createInstance);

async function main() {
  const wallet = await bitgo.coin(coin).wallets().get({ id: OFC_WALLET_ID });
  const addressBook = wallet.toAddressBook();

  const body: CreateAddressBookListingParams = {
    description: 'Description',
  };

  const response = await addressBook.createListing(body);

  console.log('Create Address Book Listing:', response);
}

main().catch((e) => console.error(e));

Step Result

You Enterprise is now discoverable in the public directory.

{
  "id": "string",
  "enterpriseId": "string",
  "description": "string",
  "name": "string",
  "owner": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

2. Create Listing Entry

Create an entry for your Go Account within your enterprise listing. This enables you and others to create connections between your Go Account and theirs.

Endpoint: Create a Listing Entry for your Enterprises Go Account

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export WALLET_ID="<YOUR_WALLET_ID>"
export DESCRIPTION="<YOUR_PUBLIC_DESCRIPTION>"

curl -X POST \
  https://app.bitgo-test.com/api/address-book/v1/listing/entry/global \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "walletId": "'"$WALLET_ID"'",
    "description": "'"$DESCRIPTION"'",
    "public": true
  }'

import { BitGoAPI } from '@bitgo/sdk-api';
import { coins } from '@bitgo/sdk-core';
import { CreateAddressBookListingEntryParams } from '@bitgo/sdk-core/dist/src/bitgo/address-book';
import * as dotenv from 'dotenv';

const OFC_WALLET_ID = process.env.OFC_WALLET_ID;

const bitgo = new BitGoAPI({
  accessToken: process.env.TESTNET_ACCESS_TOKEN,
  env: 'test',
  customRootURI: 'https://app.bitgo-test.com',
});

const coin = 'ofc';
bitgo.register(coin, coins.Ofc.createInstance);

async function main() {
  const wallet = await bitgo.coin(coin).wallets().get({ id: OFC_WALLET_ID });
  const addressBook = wallet.toAddressBook();

  const body: CreateAddressBookListingEntryParams = {
    walletId: wallet.id(),
    description: 'Public description',
    public: true,
  };

  const listingEntry = await addressBook.createListingEntry(body);

  console.log('Address Book Listing Entry:', listingEntry);
}

main().catch((e) => console.error(e));

Step Result

{
  "id": "string",
  "walletId": "string",
  "coin": "string",
  "type": "GO_ACCOUNT",
  "description": "string",
  "discoverable": true,
  "featured": true,
  "createdAt": "string",
  "updatedAt": "string"
}

3. Add a Connection

Add connections to Go Accounts you find in the directory by passing the targetListingEntryId. If a Go Account isn't listed in the directory, you can still add connection if you know the wallet ID of the partner's Go Account.

Endpoint: Add a Go Account Connection

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export LISTING_ENTRY_ID="<LISTING_ENTRY_ID>"
export LOCAL_LISTING_ENTRY_DESCRIPTION="<LOCAL_LISTING_ENTRY_DESCRIPTION>"
export TARGET_LISTING_ENTRY_ID="<TARGET_LISTING_ENTRY_ID>"

curl -X POST \
  https://app.bitgo-test.com/api/address-book/v1/connections \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "listingEntryId": "'"$LISTING_ENTRY_ID"'",
    "localListingEntryDescription": "'"$LOCAL_LISTING_ENTRY_DESCRIPTION"'",
    "targetListingEntryId": "'"$TARGET_LISTING_ENTRY_ID"'"
  }'

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export WALLET_ID="<THEIR_GO_ACCOUNT_WALLET_ID>"

curl -X POST \
  https://app.bitgo-test.com/api/address-book/v1/connections \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"walletId": "'"$WALLET_ID"'"}'

import { BitGoAPI } from '@bitgo/sdk-api';
import { coins } from '@bitgo/sdk-core';
import { CreateAddressBookConnectionParams } from '@bitgo/sdk-core/src/bitgo/address-book';
import * as dotenv from 'dotenv';

const OFC_WALLET_ID = process.env.OFC_WALLET_ID;

const bitgo = new BitGoAPI({
  accessToken: process.env.TESTNET_ACCESS_TOKEN,
  env: 'test',
  customRootURI: 'https://app.bitgo-test.com',
});

const coin = 'ofc';
bitgo.register(coin, coins.Ofc.createInstance);

async function main() {
  const wallet = await bitgo.coin('ofc').wallets().get({ id: OFC_WALLET_ID });
  const addressBook = wallet.toAddressBook();

  const listing = await addressBook.getListing();
  // Check if the wallet's listing exists and has entries
  if (!listing.listingEntries || listing.listingEntries.length === 0) {
    throw new Error('Wallet with ID ${OFC_WALLET_ID} does not have any address book listing entries.');
  }
  const listingEntry = listing.listingEntries[0];

  const directory = await addressBook.getListingEntryDirectory();
  // Check if the directory has any entries to connect with
  if (!directory.listingEntries || directory.listingEntries.length === 0) {
    throw new Error('The address book directory is empty. No available entries to connect with.');
  }
  const targetListingEntry = directory.listingEntries[0];

  const body: CreateAddressBookConnectionParams = {
    listingEntryId: listingEntry.id, // We now know this exists
    targetListingEntryId: targetListingEntry.id, // We now know this exists
    localListingEntryDescription: 'My description of the connection',
  };

  const connection = await addressBook.createConnection(body);

  console.log('Address Book Connection:', connection);
}

main().catch((e) => console.error(e));

import { BitGoAPI } from '@bitgo/sdk-api';
import { coins } from '@bitgo/sdk-core';
import { CreateAddressBookConnectionParams } from '@bitgo/sdk-core/dist/src/bitgo/address-book';
import * as dotenv from 'dotenv';

dotenv.config();

const OFC_WALLET_ID = process.env.OFC_WALLET_ID;

const bitgo = new BitGoAPI({
  accessToken: process.env.TESTNET_ACCESS_TOKEN,
  env: 'test',
  customRootURI: 'https://app.bitgo-test.com',
});

const coin = 'ofc';
bitgo.register(coin, coins.Ofc.createInstance);

async function main() {
  const wallet = await bitgo.coin(coin).wallets().get({ id: OFC_WALLET_ID });
  const addressBook = wallet.toAddressBook();

  const listing = await addressBook.getListing();
    
  if (!listing.listingEntries || listing.listingEntries.length === 0) {
    throw new Error('Wallet with ID ${OFC_WALLET_ID} does not have any address book listing entries.');
  }
  const listingEntry = listing.listingEntries[0];
  
  const body: CreateAddressBookConnectionParams = {
    listingEntryId: listingEntry.id, // my listing entry id for the wallet
    walletId: '', // ofc wallet with whom I was to add to the address book.
    localListingName: 'Manual Wallet Name',
    localListingEntryDescription: 'My description of the connection',
  };

  const connection = await addressBook.createConnection(body);

  console.log('Address Book Connection:', connection);
}

main().catch((e) => console.error(e));

Step Result

{
  "connections": [
    {
      "ownerListingEntry": {
        "listing": {
          "id": "string",
          "name": "string",
          "description": "string",
          "editable": true
        },
        "id": "string",
        "walletId": "string",
        "coin": "string",
        "type": "GO_ACCOUNT",
        "description": "string",
        "discoverable": true,
        "featured": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "targetListingEntry": {
        "listing": {
          "id": "string",
          "name": "string",
          "description": "string",
          "editable": true
        },
        "id": "string",
        "walletId": "string",
        "coin": "string",
        "type": "GO_ACCOUNT",
        "description": "string",
        "discoverable": true,
        "featured": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "id": "string", // this is the addressBookConnectionId for settlements
      "type": "DVP",
      "status": "PENDING_DEACTIVATION",
      "label": "string",
      "description": "string",
      "createdBy": "string",
      "updatedBy": "string",
      "createdAt": "string",
      "updatedAt": "string" // this is the addressBookConnectionUpdatedAt for settlements
    }
  ]
}

Next Steps

Settlements

Overview

Prerequisites

1. List your Enterprise

Step Result

2. Create Listing Entry

Step Result

3. Add a Connection

Step Result

Next Steps

See Also