REST API v1

Resources

ResourceDescription
ChallengeA one-time challenge required in the signed message when creating an order.
OrderA long-living order holding payment and payout instructions.
ExchangeAn exchange initiated by funding a previously created order.

Download our Postman Collection to find examples on how to work with these resources.

Exchange pairs

PairBase currencyQuote currency
btc/eurbtceur
btc/chfbtcchf
btc/gbpbtcgbp

Please note that cost, rate and fee are always denominated in the quote currency eur, chf or gbp, while the amount is denominated in the base currency btc.

Exchange types

TypeDescription
buyBuy base currency btc for quote currency eur, chf or gbp.
sellSell base currency btc for quote currency eur, chf or gbp.

Proof of address ownership

Pocket needs to make sure that the addresses it pays out to are controlled by its users themselves. It does this by requesting a signature that can only be produced with the private key of the receiving address. The message that is signed can be chosen freely but must contain a previously generated Challenge token.

Affiliation

All orders created through your api client automatically get affiliated to you. This means that part of the fees is attributed and paid out to you, according to the conditions defined during registration. If you have multiple agreements, you can use the optional affiliate_id field to choose which affiliate agreement to use.

Create a challenge

You'll need to create a challenge before you can create a new order. Its random token will have to be included in the message to be signed.

POST /v1/challenges


{}
201 created challenge
{
  "id": "95ab94f0-bd8d-410c-bfc8-b1f27d43b0c0",
  "token": "7v7t4Fmb",
  "expires_on": "2022-01-10T00:25:11.123Z",
  "completed_on": null
}

Get a challenge

Although unlikely, if you ever need to retrieve a previously created challenge using your client_id, you can do that very simply.

GET /v1/challenges/{id}
200 existing challenge
{
  "id": "95ab94f0-bd8d-410c-bfc8-b1f27d43b0c0",
  "token": "7v7t4Fmb",
  "expires_on": "2022-01-10T00:25:11.123Z",
  "completed_on": null
}

Create an order

An order is a long-living set of a payment and payout instructions. You create it once and it can be used for one-time Bitcoin purchases, but also for standing orders. The order also allows you to define the fee_rate applied to all exchanges (1.2% - 4.5%).

POST /v1/orders


{
  "active": true,
  "affiliate_id": "8ed13c2a-a8c6-4f0e-b43e-3fdbf1f094a6", // optional
  "fee_rate": 0.03,
  "payment_method": {
    "currency": "chf",
    "debitor_iban": "DE75512108001245126199"
  },
  "payout_method": {
    "bitcoin_address": "17wvJajWQjoVJuJe31tuiDs4MmVeBfSvGY",
    "message": "I confirm my bitcoin wallet. [7v7t4Fmb]",
    "signature": "IKiJsfsAta7Id7Seq+j8EEfpFUj2LCVDRjQ+ZC3/akv+VfUznwmq9mkxQtvqz8NTr0t6VnmTBcsEhHLMQYixHZM=",
    // optional group
    "extended_public_key": "xpub6C9cxxj5hCqTY7sYeofQPA4nXuLJpL5xBL5F874n8hremDiwrWPsPBmxjJxHqBL7jwxKy33j4uJmHXQSNxRegEY2MukehJUe8s4mBkaFGBU",
    "derivation_path": "0/1",
    "gap_limit": null // default 10
  }
}
201 created order
{
  "id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "active": true,
  "created_on": "2021-09-10T04:55:36.887Z",
  "affiliate_id": "8ed13c2a-a8c6-4f0e-b43e-3fdbf1f094a6",
  "fee_rate": 0.03,
  "payment_method": {
    "currency": "chf",
    "debitor_iban": "DE75512108001245126199",
    "creditor_reference": "RF18GW8K79",
    "creditor_iban": "CH9400778214768302002",
    "creditor_bank_name": "Luzerner Kantonalbank",
    "creditor_bank_street": "Pilatusstrasse 12",
    "creditor_bank_postal_code": "6002",
    "creditor_bank_town": "Luzern",
    "creditor_bank_country": "CH",
    "creditor_bank_bic": "LUKBCH2260A",
    "creditor_name": "Pocket App",
    "creditor_street": "Industriestrasse 33",
    "creditor_postal_code": "5242",
    "creditor_town": "Lupfig",
    "creditor_country": "CH",
    "swiss_qr_bill_payload": null
  },
  "payout_method": {
    "bitcoin_address": "17wvJajWQjoVJuJe31tuiDs4MmVeBfSvGY",
    "message": "I confirm my bitcoin wallet. [7v7t4Fmb]",
    "signature": "IKiJsfsAta7Id7Seq+j8EEfpFUj2LCVDRjQ+ZC3/akv+VfUznwmq9mkxQtvqz8NTr0t6VnmTBcsEhHLMQYixHZM=",
    "extended_public_key": "xpub6C9cxxj5hCqTY7sYeofQPA4nXuLJpL5xBL5F874n8hremDiwrWPsPBmxjJxHqBL7jwxKy33j4uJmHXQSNxRegEY2MukehJUe8s4mBkaFGBU",
    "derivation_path": "0/1",
    "gap_limit": null
  }
}

Patch an order

You can patch the active and fee_rate fields of an existing order created with your client_id at any time.

PATCH /v1/orders/{id}


{
  "active": false, // optional
  "affiliate_id": "8ed13c2a-a8c6-4f0e-b43e-3fdbf1f094a6", // optional
  "fee_rate": 0.025 // optional
}
200 patched order
{
  "id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "active": false,
  "created_on": "2021-09-10T04:55:36.887Z",
  "affiliate_id": "8ed13c2a-a8c6-4f0e-b43e-3fdbf1f094a6",
  "fee_rate": 0.025,
  "payment_method": {
    "currency": "chf",
    "debitor_iban": "DE75512108001245126199",
    "creditor_reference": "RF18GW8K79",
    "creditor_iban": "CH9400778214768302002",
    "creditor_bank_name": "Luzerner Kantonalbank",
    "creditor_bank_street": "Pilatusstrasse 12",
    "creditor_bank_postal_code": "6002",
    "creditor_bank_town": "Luzern",
    "creditor_bank_country": "CH",
    "creditor_bank_bic": "LUKBCH2260A",
    "creditor_name": "Pocket App",
    "creditor_street": "Industriestrasse 33",
    "creditor_postal_code": "5242",
    "creditor_town": "Lupfig",
    "creditor_country": "CH",
    "swiss_qr_bill_payload": null
  },
  "payout_method": {
    "bitcoin_address": "17wvJajWQjoVJuJe31tuiDs4MmVeBfSvGY",
    "message": "I confirm my bitcoin wallet. [7v7t4Fmb]",
    "signature": "IKiJsfsAta7Id7Seq+j8EEfpFUj2LCVDRjQ+ZC3/akv+VfUznwmq9mkxQtvqz8NTr0t6VnmTBcsEhHLMQYixHZM=",
    "extended_public_key": "xpub6C9cxxj5hCqTY7sYeofQPA4nXuLJpL5xBL5F874n8hremDiwrWPsPBmxjJxHqBL7jwxKy33j4uJmHXQSNxRegEY2MukehJUe8s4mBkaFGBU",
    "derivation_path": "0/1",
    "gap_limit": null
  }
}

Get an order

You can retrieve all orders created using your client_id at any time.

GET /v1/orders/{id}
200 existing order
{
  "id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "active": true,
  "created_on": "2021-09-10T04:55:36.887Z",
  "affiliate_id": "8ed13c2a-a8c6-4f0e-b43e-3fdbf1f094a6",
  "fee_rate": 0.03,
  "payment_method": {
    "currency": "chf",
    "debitor_iban": "DE75512108001245126199",
    "creditor_reference": "RF18GW8K79",
    "creditor_iban": "CH9400778214768302002",
    "creditor_bank_name": "Luzerner Kantonalbank",
    "creditor_bank_street": "Pilatusstrasse 12",
    "creditor_bank_postal_code": "6002",
    "creditor_bank_town": "Luzern",
    "creditor_bank_country": "CH",
    "creditor_bank_bic": "LUKBCH2260A",
    "creditor_name": "Pocket App",
    "creditor_street": "Industriestrasse 33",
    "creditor_postal_code": "5242",
    "creditor_town": "Lupfig",
    "creditor_country": "CH",
    "swiss_qr_bill_payload": null
  },
  "payout_method": {
    "bitcoin_address": "17wvJajWQjoVJuJe31tuiDs4MmVeBfSvGY",
    "message": "I confirm my bitcoin wallet. [7v7t4Fmb]",
    "signature": "IKiJsfsAta7Id7Seq+j8EEfpFUj2LCVDRjQ+ZC3/akv+VfUznwmq9mkxQtvqz8NTr0t6VnmTBcsEhHLMQYixHZM=",
    "extended_public_key": "xpub6C9cxxj5hCqTY7sYeofQPA4nXuLJpL5xBL5F874n8hremDiwrWPsPBmxjJxHqBL7jwxKy33j4uJmHXQSNxRegEY2MukehJUe8s4mBkaFGBU",
    "derivation_path": "0/1",
    "gap_limit": null
  }
}

Get an exchange

You can retrieve all exchanges initiated by orders created using your client_id at any time.

GET /v1/exchanges/{id}
200 executed exchange
{
  "id": "a2d75998-5ee5-4501-a4cf-4e3788732b7a",
  "order_id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "fee_rate": 0.015,
  "pair": "btc/chf",
  "type": "buy",
  "cost": 100.00,
  "executed_on": "2021-09-15T14:35:10.122Z",
  "amount": 0.00197000,
  "rate": 50000.00,
  "fee": 1.50,
  "action": null,
  "reason": null,
  "payout": null
}
200 interrupted exchange
{
  "id": "a2d75998-5ee5-4501-a4cf-4e3788732b7a",
  "order_id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "fee_rate": 0.015,
  "pair": "btc/chf",
  "type": "buy",
  "cost": 100.00,
  "executed_on": null,
  "amount": null,
  "rate": null,
  "fee": null,
  "action": {
    "code": "identification_required",
    "identification_id": "7bf967b5-3d34-4cd6-936c-6631811401d2"
  },
  "reason": null,
  "payout": null
}
200 refunded exchange
{
  "id": "a2d75998-5ee5-4501-a4cf-4e3788732b7a",
  "order_id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "fee_rate": 0.015,
  "pair": "btc/chf",
  "type": "buy",
  "cost": 100.00,
  "executed_on": null,
  "amount": null,
  "rate": null,
  "fee": null,
  "action": null,
  "reason": {
    "code": "threshold_exceeded"
  },
  "payout": null
}
200 settled exchange
{
  "id": "a2d75998-5ee5-4501-a4cf-4e3788732b7a",
  "order_id": "64decab6-4129-4fe7-9f6e-1db68283f5ce",
  "fee_rate": 0.015,
  "pair": "btc/chf",
  "type": "buy",
  "cost": 100.00,
  "executed_on": "2021-09-15T14:35:10.122Z",
  "amount": 0.00197000,
  "rate": 50000.00,
  "fee": 1.50,
  "action": null,
  "reason": null,
  "payout": {
    "txid": "c01c7a0fd270aa3876119098c0e2d51687a795efab99787e214d8a93ab9f8342",
    "outpoint": 1,
    "bitcoin_address": "bc1q5vvayqt3n4alhjaxy6ql4w2fs6r0y83rmvh3tg",
    "derivation_path": null,
    "block_height": null,
    "confirmed": false,
    "fee": 0.00000190,
    "amount": 0.0019681
  }
}