Contract Management API

Endpoints to manage the contracts for an Account.

Create a Loan Contract

Create an ARC Contract for a given Account ID using the API Key for that Account. The Account ID for the API Key used must be either the Borrower or Lender.

Request format

method: 'POST'
endpoint: '/api/external/arc/contract'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }
body: {
  "fiatLoanValue": 10000,
  "collateralPercentage": 1.3,
  "interestRate": 0.08,
  "maintenanceMargin": 1.2,
  "closeOutMargin": 1.1,
  "term": {
    "numPeriods": 3,
    "periodType": "months"
  },
  "borrowerAccountId": "the borrower's Account ID",
  "lenderAccountId": "the lender's Account ID",
  "allowOverCollateralization": true,
  "contractType": "loan",
  "payoutCurrency": "btc",
  "collateralGracePeriod": 3,
  "compoundingUnitsPerYear": 12
}

Response format

{
  "borrowerAccountId": "string",
  "lenderAccountId": "string",
  "fiatLoanValue": 0,
  "collateralPercentage": 0,
  "interestRate": 0,
  "maintenanceMargin": 0,
  "closeOutMargin": 0,
  "term": {},
  "allowOverCollateralization": true,
  "contractType": "string",
  "payoutCurrency": "string",
  "compoundingUnitsPerYear": 0,
  "collateralGracePeriod": 0,
  "initialBitcoinPrice": 0,
  "fiatPrinciple": 0,
  "state": "string",
  "start": 0,
  "accruedInterest": 0,
  "counterparties": [
    "string"
  ]
}

Get All Contracts

Gets a list of all the contracts your account is a counterparty to. An optional filter is available for showing only active or including inactive contracts.

Request format

method: 'GET'
endpoint: '/api/external/arc/contract?'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }
params: active=boolean (default is false to show all contracts)

Response format

[
    {
        "_id": "66057aafd45018fe62ee753c",
        "fiatLoanValue": 20000,
        "collateralPercentage": 1.5,
        "initialBitcoinPrice": 70422.62,
        "fiatPrinciple": 30000,
        "interestRate": 0.05,
        "maintenanceMargin": 1.2,
        "closeOutMargin": 1.1,
        "expiry": 1711721519715,
        "allowOverCollateralization": true,
        "contractType": "loan",
        "payoutCurrency": "usd",
        "depositAddress": "",
        "state": "approved",
        "collateralGracePeriod": 3,
        "counterparties": [
            {
                "accountId": "Borrower account ID",
                "counterpartyType": "borrower"
            },
            {
                "accountId": "Lender account ID",
                "counterpartyType": "lender"
            }
        ]
    }
]

Get a Specific Contract

Retrieve a specific Contract. You must be a counterparty to the Contract to retrieve it.

Request format

method: 'GET'
endpoint: '/api/external/arc/contract/{contractId}'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }

Response format

{
    "_id": "669d3ca3e04e1d7c45507abe",
    "fiatLoanValue": 10000,
    "collateralPercentage": 1.3,
    "initialBitcoinPrice": 0,
    "fiatPrinciple": 13000,
    "interestRate": 0.08,
    "maintenanceMargin": 1.2,
    "closeOutMargin": 1.1,
    "term": {
        "numPeriods": 3,
        "periodType": "months"
    },
    "allowOverCollateralization": true,
    "contractType": "loan",
    "payoutCurrency": "btc",
    "state": "created",
    "collateralGracePeriod": 3,
    "accruedInterest": 0,
    "compoundingUnitsPerYear": 12,
    "start": 1721580707815,
    "priceFeeds": [
        "coinbase",
        "coingecko",
        "coincap"
    ],
    "__v": 0,
    "counterparties": [
        {
            "accountId": "Borrower Account ID",
            "counterpartyType": "borrower"
        },
        {
            "accountId": "Lender Account ID",
            "counterpartyType": "lender"
        }
    ]
}

Get The Contract Deposit Address

To fund a contract, you can retrieve the Bitcoin Wallet Address for the Contract to deposit Bitcoin as collateral. You must be the Borrower in a Loan Contract to retrieve this.

Request format

method: 'GET'
endpoint: '/api/external/arc/contract/{contractId}/deposit-information'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }

Response format

{
    "depositAddress": "bitcoin wallet address"
}

Update Contract Details

While a contract has not been approved by either counterparty, either counterparty can update the contract terms and conditions. Any of the fields in the body below can be passed in. Only those passed will be updated. Some fields like fiatLoanValue, will impact other fields on the response such as fiatPrinciple which are calculations based on fiatLoanValue and collateralPercentage.

Request format

method: 'PUT'
endpoint: '/api/external/arc/contract/{contractId}'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }
body: {
  "allowOverCollateralization": true,
  "fiatLoanValue": 12000,
  "closeOutMargin": 1.1,
  "maintenanceMargin": 1.2,
  "collateralGracePeriod": 3,
  "compoundingUnitsPerYear": 12,
  "interestRate": 0.08,
  "collateralPercentage": 1.5,
  "term": {
    "numPeriods": 24,
    "periodType": "hours"
  }
}

Response format

{
    "_id": "6679d44677376ed749b42588",
    "fiatLoanValue": 12000,
    "collateralPercentage": 1.5,
    "initialBitcoinPrice": 0,
    "fiatPrinciple": 18000,
    "interestRate": 0.08,
    "maintenanceMargin": 1.2,
    "closeOutMargin": 1.1,
    "term": {
        "numPeriods": 24,
        "periodType": "hours"
    },
    "allowOverCollateralization": true,
    "contractType": "loan",
    "payoutCurrency": "btc",
    "state": "created",
    "collateralGracePeriod": 3,
    "accruedInterest": 0,
    "compoundingUnitsPerYear": 12,
    "start": 1719260230025,
    "priceFeeds": [
        "coinbase",
        "coingecko",
        "coincap"
    ],
    "counterparties": [
        {
            "accountId": "Borrower Account ID",
            "counterpartyType": "borrower"
        },
        {
            "accountId": "Lender Account ID",
            "counterpartyType": "lender"
        }
    ]
}

Terminate a Contract

Contracts that have not been approved by both counterparties can be terminated or cancelled.

Request format

method: 'DELETE'
endpoint: '/api/external/arc/contract/{contractId}'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }

Response format

{
    "contractId": "Contract ID that was cancelled"
}

Set Withdrawal Address

Each counterparty can set their withdrawal address for sending funds to an on-chain Bitcoin Wallet address. If this is not set, funds at settlement will be placed in the Lightning node's wallet. Funds can then be transferred at a later time. Recommendation is to set the withdrawal address so that funds are immediately transferred upon contract settlement

Request format

method: 'PUT'
endpoint: '/api/external/arc/contract/{contractId}/withdrawal-address'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }
body: {
    "withdrawalAddress": "The Bitcoin wallet address to withdraw funds to at settlement"
}

Response format

{}

Approve a Contract

As a counterparty to a contract, you can choose to approve the terms and conditions.

Request format

method: 'PUT'
endpoint: '/api/external/arc/contract/{contractId}/approve'
headers: { 'Content-Type': 'application/json', 'X-API-KEY': 'your api key' }

Response format

{
    "counterparties": [
        {
            "accountId": "Borrower Account ID",
            "counterpartyType": "borrower"
        },
        {
            "accountId": "Lender Account ID",
            "counterpartyType": "lender"
        }
    ],
    "contractApprovals": [
        {
            "contractId": "Contract ID",
            "accountId": "The Account ID of who just approved",
            "approvalTime": Timestamp of the approval
        }
    ]
}