{
  "info": {
    "name": "BitGo OES - Partner Flows",
    "description": "Postman collection for BitGo Off Exchange Settlement (OES) — Partner integration flows.\n\nPartners are users who operate trading platforms that connect to BitGo to enable client trading.\n\nFlow order:\n1. Prerequisites — Verify access, enterprise, and wallet setup\n2. Connections — View and manage client connections to your platform\n3. Allocations — View client asset allocations\n4. Deallocations — View client deallocation requests\n5. Settlements — Create and sign settlements to move assets off-chain\n6. View Details — Check balances and settlement history\n\nPartner Webhook Endpoints (your platform must implement):\n- POST /bitgo/v1/connections — Receive client connection requests\n- POST /bitgo/v1/allocations — Receive client allocation requests\n- POST /bitgo/v1/deallocations — Receive client deallocation requests\n- PUT /bitgo/v1/deallocations/:id — Confirm deallocation release\n\nSetup:\n1. Import this collection into Postman\n2. Set the collection variables below (click the collection name → Variables tab)\n3. Set baseUrl to Testnet (https://app.bitgo-test.com) or Production (https://app.bitgo.com)\n4. Set your access_token and enterprise_id\n5. Follow the folder order\n\nReferences:\n- OES Overview: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-overview\n- Partner Overview: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-overview\n- Partner Signature: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-signature\n- Partner Connect: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-connect\n- Partner Allocate: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-allocate\n- Partner Deallocate: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-deallocate\n- Partner Settlements: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-settlements\n- Partner View Details: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-view-details\n- Asset Precision: https://developers.bitgo.com/docs/go-network-off-exchange-settlement-partner-asset-precision\n- API Reference: https://developers.bitgo.com/reference",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://app.bitgo-test.com",
      "description": "BitGo API base URL. Testnet: https://app.bitgo-test.com | Production: https://app.bitgo.com"
    },
    {
      "key": "expressHost",
      "value": "http://localhost:3080",
      "description": "BitGo Express host for payload signing. Default: http://localhost:3080"
    },
    {
      "key": "access_token",
      "value": "",
      "description": "Your BitGo access token. Required scopes: ofc_view, ofc_manage, network_view, network_manage"
    },
    {
      "key": "enterprise_id",
      "value": "",
      "description": "Your enterprise ID (found in BitGo dashboard or via Get Current User Profile)"
    },
    {
      "key": "ofc_wallet_id",
      "value": "",
      "description": "Your OFC (off-chain) trading account wallet ID. Retrieve via List OFC Wallets"
    },
    {
      "key": "connection_id",
      "value": "",
      "description": "A client's connection ID. Retrieve via List Partner Connections"
    },
    {
      "key": "settlement_id",
      "value": "",
      "description": "Settlement ID to query. Retrieve via List Partner Settlements"
    },
    {
      "key": "signed_payload",
      "value": "",
      "description": "Signed payload string from BitGo Express / JS SDK"
    },
    {
      "key": "signature",
      "value": "",
      "description": "Cryptographic signature from BitGo Express / JS SDK"
    },
    {
      "key": "nonce",
      "value": "1",
      "description": "Nonce for request signing. Increment with each request"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{access_token}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "Prerequisites",
      "description": "Verify your environment before using OES partner flows.",
      "item": [
        {
          "name": "Get Current User Profile",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v2/user/me",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v2", "user", "me"]
            },
            "description": "Returns the current authenticated user's profile. Use this to verify your access token is working."
          }
        },
        {
          "name": "Get Enterprise Info",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v2/enterprise/{{enterprise_id}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v2", "enterprise", "{{enterprise_id}}"]
            },
            "description": "Returns details about your enterprise, including licenses. Verify that your enterprise has the OES partner license enabled."
          }
        },
        {
          "name": "List OFC Wallets",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v2/ofc/wallet?enterprise={{enterprise_id}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v2", "ofc", "wallet"],
              "query": [
                {
                  "key": "enterprise",
                  "value": "{{enterprise_id}}"
                }
              ]
            },
            "description": "Lists all OFC (off-chain) wallets for your enterprise. Your trading account will be an OFC wallet. Save the wallet ID as {{ofc_wallet_id}}."
          }
        },
        {
          "name": "Get OFC Wallet Balance",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v2/ofc/wallet/{{ofc_wallet_id}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v2", "ofc", "wallet", "{{ofc_wallet_id}}"]
            },
            "description": "Get details and balances for your trading account wallet."
          }
        }
      ]
    },
    {
      "name": "1. Client Connections",
      "description": "View client connections to your partner platform.\n\nWhen a client initiates a connection, BitGo sends your platform a webhook:\nPOST /bitgo/v1/connections\n\nYour platform must verify the X-BitGo-Signature header, validate the connection token, and respond with partnersClientId and partnersConnectionId.",
      "item": [
        {
          "name": "List Partner Connections",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/connections",
              "host": ["{{baseUrl}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "connections"]
            },
            "description": "Lists all client connections to your partner platform. Each connection represents a client account linked to your trading platform."
          }
        }
      ]
    },
    {
      "name": "2. Allocations",
      "description": "View client asset allocations to your platform.\n\nWhen a client allocates assets, BitGo sends your platform a webhook:\nPOST /bitgo/v1/allocations\n\nYour platform should credit the client's trading account with the allocated amount.",
      "item": [
        {
          "name": "List Partner Allocations",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/allocations",
              "host": ["{{baseUrl}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "allocations"]
            },
            "description": "Lists all allocations from clients to your partner platform, including status (pending, cleared, rejected)."
          }
        }
      ]
    },
    {
      "name": "3. Deallocations",
      "description": "View client deallocation requests.\n\nWhen a client requests a deallocation, BitGo sends your platform two webhooks:\n1. POST /bitgo/v1/deallocations — Reserve the amount on your platform\n2. PUT /bitgo/v1/deallocations/:id — Confirm the release (safe to credit client at BitGo)",
      "item": [
        {
          "name": "List Partner Deallocations",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/deallocations",
              "host": ["{{baseUrl}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "deallocations"]
            },
            "description": "Lists all deallocation requests from clients, including status."
          }
        }
      ]
    },
    {
      "name": "4. Create Settlements",
      "description": "Settlement endpoints for partners. Settlements transfer assets off-chain between partner and client accounts at BitGo Trust.\n\nSettlements must occur during a pre-determined window, typically once every 24 hours.\n\nSettlement amounts:\n- Positive values = assets moving TO the partner (client owes partner)\n- Negative values = assets moving FROM the partner (partner owes client)\n\nSteps:\n1. Build settlement amounts for each connection\n2. Get signing payload via BitGo Express\n3. Sign with trading account private key\n4. Submit the signed settlement request",
      "item": [
        {
          "name": "Get Settlement Signing Payload",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"externalId\": \"settlement-001\",\n  \"notes\": \"Daily settlement\",\n  \"settlementAmounts\": {\n    \"{{connection_id}}\": {\n      \"ofcbtc\": \"100000\",\n      \"ofceth\": \"-50000000000000000\"\n    }\n  },\n  \"nonce\": \"{{nonce}}\"\n}"
            },
            "url": {
              "raw": "{{expressHost}}/api/network/v1/enterprises/{{enterprise_id}}/partners/settlements-signing",
              "host": ["{{expressHost}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "settlements-signing"]
            },
            "description": "Generates a signing payload for a settlement request. Send this to BitGo Express to get the payload signed with your trading account's private key.\n\nNote: This endpoint uses BitGo Express ({{expressHost}}, default localhost:3080)."
          }
        },
        {
          "name": "Perform Partner Settlement",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"externalId\": \"settlement-001\",\n  \"notes\": \"Daily settlement\",\n  \"settlementAmounts\": {\n    \"{{connection_id}}\": {\n      \"ofcbtc\": \"100000\",\n      \"ofceth\": \"-50000000000000000\"\n    }\n  },\n  \"nonce\": \"{{nonce}}\",\n  \"payload\": \"{{signed_payload}}\",\n  \"signature\": \"{{signature}}\"\n}"
            },
            "url": {
              "raw": "{{expressHost}}/api/network/v1/enterprises/{{enterprise_id}}/partners/settlements",
              "host": ["{{expressHost}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "settlements"]
            },
            "description": "Submits a signed settlement request. Settlement requests must be cryptographically signed for integrity and nonrepudiation.\n\nNote: This endpoint uses BitGo Express ({{expressHost}}, default localhost:3080)."
          }
        }
      ]
    },
    {
      "name": "5. View Go Network Details",
      "description": "View balances and settlement history for your partner account.",
      "item": [
        {
          "name": "Get Partner Balances",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/balances",
              "host": ["{{baseUrl}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "balances"]
            },
            "description": "Returns aggregate balances for the partner across all client connections."
          }
        },
        {
          "name": "Get Partner Network Balances",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/networkBalances",
              "host": ["{{baseUrl}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "networkBalances"]
            },
            "description": "Returns balances broken down by client connection, showing available and held amounts for each connected client."
          }
        },
        {
          "name": "List Partner Settlements",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/settlements",
              "host": ["{{baseUrl}}"],
              "path": ["api", "network", "v1", "enterprises", "{{enterprise_id}}", "partners", "settlements"]
            },
            "description": "Lists all settlements initiated by the partner, including status (completed, pending, rejected)."
          }
        },
        {
          "name": "Get Settlement by ID",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/network/v1/enterprises/{{enterprise_id}}/partners/settlements/{{settlement_id}}",
              "host": ["{{baseUrl}}"],
              "path": [
                "api",
                "network",
                "v1",
                "enterprises",
                "{{enterprise_id}}",
                "partners",
                "settlements",
                "{{settlement_id}}"
              ]
            },
            "description": "Returns details of a specific settlement by ID."
          }
        }
      ]
    }
  ]
}