Bull Bitcoin

Bull Bitcoin API Documentation

This document provides documentation for the Bull Bitcoin API, covering endpoints for buying, selling, and managing funds.

Summary of Endpoints

Orders

Users

Recipients

Onboarding and KYC

Before using the API, all users must complete the onboarding and KYC (Know Your Customer) process. This process is not API-driven and is handled through an iframe integration. Please contact Bull Bitcoin for more information on how to integrate the KYC iframe.

Authentication

All API requests must be authenticated using an API key. The API key must be included in the X-API-Key header of each request.

X-API-Key: YOUR_API_KEY

Endpoints

The base URL for the API is https://bullbitcoin.com/api. The API uses a JSON-RPC 2.0 interface. All requests are POST requests.

Orders

Create Buy Order

Creates a new buy order.

Endpoint: /ak/api-orders

Method: createOrderBuy

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "createOrderBuy",
  "params": {
    "fiatCurrency": "CAD",
    "network": "bitcoin",
    "isOwner": true,
    "address": "bc1...",
    "fiatAmount": 100.50
  }
}

Parameters:

Name Type Description
fiatCurrency String The fiat currency to use for the order. Supported values are CAD, USD, EUR, MXN, CRC.
network String The Bitcoin network to use. Supported values are bitcoin, liquid.
isOwner Boolean Whether the user is the owner of the address.
address String The Bitcoin or Liquid address to send the funds to.
fiatAmount Number The amount of the order in fiat currency. Mutually exclusive with bitcoinAmount.
bitcoinAmount Number The amount of the order in Bitcoin. Mutually exclusive with fiatAmount.

Response:

A BuyOrder object.

{
    "orderId": "string",
    "orderType": "Buy Bitcoin",
    "orderSubtype": "string",
    "message": {
        "code": "string",
        "message": "string"
    },
    "orderNumber": "integer",
    "payinAmount": "number",
    "payinCurrency": "string",
    "payoutAmount": "number",
    "payoutCurrency": "string",
    "exchangeRateAmount": "number",
    "exchangeRateCurrency": "string",
    "payinMethod": "E-Transfer",
    "payoutMethod": "Bitcoin",
    "orderStatus": "Awaiting confirmation",
    "payinStatus": "Not started",
    "payoutStatus": "Not started",
    "confirmationDeadline": "string",
    "createdAt": "string",
    "scheduledPayoutTime": "string",
    "lightningInvoice": "string",
    "bitcoinAddress": "string",
    "bitcoinTransactionId": "string",
    "liquidAddress": "string",
    "liquidTransactionId": "string",
    "lightningAddress": "string",
    "lnUrl": "string",
    "beneficiaryName": "string",
    "beneficiaryLabel": "string",
    "beneficiaryAccountNumber": "string",
    "completedAt": "string",
    "sentAt": "string",
    "isPPBitcoinOutUpdatable": "boolean",
    "payinAmountChanged": {
        "requestedAmount": "number",
        "receivedAmount": "number"
    },
    "indexRateAmount": "number",
    "indexRateCurrency": "string",
    "lightningVoucherExpiresAt": "string",
    "unbatchedBuyOnchainFees": "number",
    "isTestnet": "boolean"
}

Confirm Buy Order

Confirms a previously created buy order.

Endpoint: /ak/api-orders

Method: confirmOrderSummary

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "confirmOrderSummary",
  "params": {
    "orderId": "ORDER_ID"
  }
}

Parameters:

Name Type Description
orderId String The ID of the order to confirm.

Response:

A BuyOrder object.

Create Sell Order

Creates a new sell order.

Endpoint: /ak/api-orders

Method: sellToBalance

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "sellToBalance",
  "params": {
    "fiatCurrency": "CAD",
    "bitcoinNetwork": "bitcoin",
    "fiatAmount": 100.50
  }
}

Parameters:

Name Type Description
fiatCurrency String The fiat currency to use for the order. Supported values are CAD, USD, EUR, MXN, CRC.
bitcoinNetwork String The Bitcoin network to use. Supported values are bitcoin, liquid.
fiatAmount Number The amount of the order in fiat currency. Mutually exclusive with bitcoinAmount.
bitcoinAmount Number The amount of the order in Bitcoin. Mutually exclusive with fiatAmount.

Response:

A SellOrder object.

{
    "orderId": "string",
    "orderType": "Sell Bitcoin",
    "orderSubtype": "string",
    "message": {
        "code": "string",
        "message": "string"
    },
    "orderNumber": "integer",
    "payinAmount": "number",
    "payinCurrency": "string",
    "payoutAmount": "number",
    "payoutCurrency": "string",
    "exchangeRateAmount": "number",
    "exchangeRateCurrency": "string",
    "payinMethod": "Bitcoin",
    "payoutMethod": "E-Transfer",
    "orderStatus": "Awaiting confirmation",
    "payinStatus": "Not started",
    "payoutStatus": "Not started",
    "confirmationDeadline": "string",
    "createdAt": "string",
    "scheduledPayoutTime": "string",
    "lightningInvoice": "string",
    "bitcoinAddress": "string",
    "bitcoinTransactionId": "string",
    "liquidAddress": "string",
    "liquidTransactionId": "string",
    "lightningAddress": "string",
    "lnUrl": "string",
    "beneficiaryName": "string",
    "beneficiaryLabel": "string",
    "beneficiaryAccountNumber": "string",
    "beneficiaryETransferAddress": "string",
    "securityQuestion": "string",
    "securityAnswer": "string",
    "paymentDescription": "string",
    "completedAt": "string",
    "sentAt": "string",
    "isPPBitcoinOutUpdatable": "boolean",
    "payinAmountChanged": {
        "requestedAmount": "number",
        "receivedAmount": "number"
    },
    "indexRateAmount": "number",
    "indexRateCurrency": "string",
    "lightningVoucherExpiresAt": "string",
    "isTestnet": "boolean"
}

Create Withdrawal Order

Creates a new withdrawal order.

Endpoint: /ak/api-orders

Method: createWithdrawalOrder

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "createWithdrawalOrder",
  "params": {
    "fiatAmount": 100.50,
    "recipientId": "RECIPIENT_ID",
    "paymentProcessor": "interac"
  }
}

Parameters:

Name Type Description
fiatAmount Number The amount of the withdrawal in fiat currency.
recipientId String The ID of the recipient to withdraw to.
paymentProcessor String The payment processor to use for the withdrawal.

Response:

A WithdrawOrder object.

{
    "orderId": "string",
    "orderType": "Withdraw",
    "orderSubtype": "string",
    "message": {
        "code": "string",
        "message": "string"
    },
    "orderNumber": "integer",
    "payinAmount": "number",
    "payinCurrency": "string",
    "payoutAmount": "number",
    "payoutCurrency": "string",
    "exchangeRateAmount": "number",
    "exchangeRateCurrency": "string",
    "payinMethod": "CAD Balance",
    "payoutMethod": "E-Transfer",
    "orderStatus": "Awaiting confirmation",
    "payinStatus": "Not started",
    "payoutStatus": "Not started",
    "confirmationDeadline": "string",
    "createdAt": "string",
    "scheduledPayoutTime": "string",
    "beneficiaryName": "string",
    "beneficiaryLabel": "string",
    "beneficiaryAccountNumber": "string",
    "beneficiaryETransferAddress": "string",
    "securityQuestion": "string",
    "securityAnswer": "string",
    "paymentDescription": "string",
    "completedAt": "string",
    "sentAt": "string",
    "isTestnet": "boolean"
}

Create Pay Order (sellToRecipient)

Creates a new pay order, allowing a user to sell bitcoin from their balance and have the fiat equivalent sent to a pre-defined recipient. This endpoint is referred to as createPayOrder in the client code.

Endpoint: /ak/api-orders

Method: sellToRecipient

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "sellToRecipient",
  "params": {
    "recipientId": "RECIPIENT_ID",
    "paymentProcessor": "interac",
    "bitcoinNetwork": "bitcoin",
    "fiatAmount": 100.50
  }
}

Parameters:

Name Type Description
recipientId String The ID of the recipient to send the funds to.
paymentProcessor String The payment processor to use for the transaction.
bitcoinNetwork String The Bitcoin network to use. Supported values are bitcoin, liquid.
fiatAmount Number The amount of the order in fiat currency. Mutually exclusive with bitcoinAmount.
bitcoinAmount Number The amount of the order in Bitcoin. Mutually exclusive with fiatAmount.

Response:

A FiatPaymentOrder object.

{
    "orderId": "string",
    "orderType": "Fiat Payment",
    "orderSubtype": "string",
    "message": {
        "code": "string",
        "message": "string"
    },
    "orderNumber": "integer",
    "payinAmount": "number",
    "payinCurrency": "string",
    "payoutAmount": "number",
    "payoutCurrency": "string",
    "exchangeRateAmount": "number",
    "exchangeRateCurrency": "string",
    "payinMethod": "Bitcoin",
    "payoutMethod": "E-Transfer",
    "orderStatus": "Awaiting confirmation",
    "payinStatus": "Not started",
    "payoutStatus": "Not started",
    "confirmationDeadline": "string",
    "createdAt": "string",
    "scheduledPayoutTime": "string",
    "beneficiaryName": "string",
    "beneficiaryLabel": "string",
    "beneficiaryAccountNumber": "string",
    "beneficiaryETransferAddress": "string",
    "securityQuestion": "string",
    "securityAnswer": "string",
    "paymentDescription": "string",
    "completedAt": "string",
    "sentAt": "string",
    "payinAmountChanged": {
        "requestedAmount": "number",
        "receivedAmount": "number"
    },
    "indexRateAmount": "number",
    "indexRateCurrency": "string",
    "isTestnet": "boolean"
}

Refresh Order Summary

Refreshes the summary of a specific order.

Endpoint: /ak/api-orders

Method: refreshOrderSummary

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "refreshOrderSummary",
  "params": {
    "orderId": "ORDER_ID"
  }
}

Parameters:

Name Type Description
orderId String The ID of the order to refresh.

Response:

An Order object (BuyOrder, SellOrder, etc.).

Unbatch and Express Order

Unbatches and expresses a specific order.

Endpoint: /ak/api-orders

Method: unbatchAndExpressOrder

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "unbatchAndExpressOrder",
  "params": {
    "orderId": "ORDER_ID"
  }
}

Parameters:

Name Type Description
orderId String The ID of the order to unbatch and express.

Response:

A BuyOrder object.

Get Order Summary

Retrieves the summary of a specific order.

Endpoint: /ak/api-orders

Method: getOrderSummary

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "getOrderSummary",
  "params": {
    "orderId": "ORDER_ID"
  }
}

Parameters:

Name Type Description
orderId String The ID of the order to retrieve.

Response:

An Order object (BuyOrder, SellOrder, etc.).

List Order Summaries

Retrieves a list of order summaries.

Endpoint: /ak/api-orders

Method: listOrderSummaries

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "listOrderSummaries",
  "params": {
    "sortBy": {
      "id": "createdAt",
      "sort": "desc"
    }
  }
}

Parameters:

Name Type Description
sortBy Object The sorting parameters for the list.
sortBy.id String The field to sort by.
sortBy.sort String The sort order (asc or desc).

Response:

An array of Order objects.

Users

Get User Summary

Retrieves the user summary.

Endpoint: /ak/api-users

Method: getUserSummary

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getUserSummary",
  "params": {}
}

Response:

A UserSummary object.

{
    "id": "string",
    "isBusiness": "boolean",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "balances": [
        {
            "currencyCode": "string",
            "amount": "number"
        }
    ]
}

Recipients

List Recipients

Retrieves a list of recipients.

Endpoint: /ak/api-recipients

Method: listRecipients

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "listRecipients",
  "params": {}
}

Response:

An array of Recipient objects. The paymentProcessors field in each Recipient object contains a list of available payment processors for that recipient.

List Fiat Recipients

Retrieves a list of fiat recipients.

Endpoint: /ak/api-recipients

Method: listRecipientsFiat

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "listRecipientsFiat",
  "params": {}
}

Response:

An array of Recipient objects.

Get Funding Details

Retrieves the funding details for a specific set of parameters.

Endpoint: /ak/api-recipients

Method: getFundingDetails

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "getFundingDetails",
  "params": {
    "paymentMethod": "interac",
    "fiatCurrency": "CAD"
  }
}

Parameters:

Name Type Description
paymentMethod String The payment method to retrieve funding details for.
fiatCurrency String The fiat currency to retrieve funding details for.

Response:

A FundingDetails object.

{
    "paymentMethod": "string",
    "fiatCurrency": "string",
    "beneficiaryName": "string",
    "beneficiaryAddress": "string",
    "beneficiaryEmail": "string",
    "securityQuestion": "string",
    "securityAnswer": "string",
    "institutionNumber": "string",
    "transitNumber": "string",
    "accountNumber": "string"
}

Enums

This section lists the enums used in the API and their possible values.

FiatCurrency

Value
USD
CAD
CRC
EUR
MXN

OrderType

Value
Buy Bitcoin
Sell Bitcoin
Fiat Payment
Funding
Withdraw
Reward
Refund
Balance Adjustment

OrderBitcoinNetwork

Value
bitcoin
liquid
lightning

OrderStatus

Value
Canceled
Payment deadline expired
In progress
Awaiting confirmation
Completed
Rejected

OrderPayinStatus

Value
Not started
Awaiting payment
In progress
Under review
Awaiting confirmation
Completed
Rejected

OrderPayoutStatus

Value
Not started
In progress
Scheduled
Awaiting claim
Completed
Canceled

OrderPaymentMethod

Value
E-Transfer
Bill payment
Bank transfer
Loadhub
SEPA
IBAN
SINPE
CAD Balance
EUR Balance
MXN Balance
CRC Balance
USD Balance
Bitcoin
Liquid
Lightning address
Lightning invoice
Lightning (LNURL)
Referral CAD
Referral EUR
Referral MXN
Referral USD
Referral CRC
SPEI
Thin Air
Refund CRC
Refund USD