API

Use the api to make requests to Insticce. The api expects and responds with JSON.

Errors

If anything goes wrong the response will have this format:

{ error: "message indicating what happened" }

Address Request

Address requests ask us to provide a unique payment address that we will watch for 24 hours. You must include your own address where you want payments forwarded to.

url: https://insticce.com/address

method: POST

JSON Parameters

forwarding_address:

A valid BCH address or set of addresses in legacy or cashaddress format. There is no default value. This is the BCH address you want payments forwarded to. Every payment we receive less the fee rate will be sent to this address. We watch the address for 24 hours, after which we stop monitoring the address and it can be discarded.

There are three possible forwarding_address formats.

  1. For a single address, use a string
    'bchtest:qr3qdt8l70pzx74w3kvzm36zvrn3c77t0ver3xxhg8'
  2. For multiple addresses, that will each receive a percentage of the payment, use an object like the following:
    {
      'bchtest:qp965cur2a5e4g4y75zd6w356daeylp4q57c8swn7g': 40, // send this address 40% of each payment 
      'bchtest:qz97n6fdve9ea92cxtwxqka572nsr9km9qu9u8ur6y': 30, // send this address 30% of each payment
      'bchtest:qrmefqlr5d50ts05ukpd4kr4due45hvusgjdsexmkx': 28.7, // send this address 28.7% of each payment
      'bchtest:qqd7erps55s6tgz7rcsqg5rtj8djvnjcmg0ldpfxet': 1.3, // send this address 1.3 % of each payment
    }
    						
    It is important that the values add up to 100 percent.
  3. For multiple addresses that receive set amounts of satoshis per payment, use an array of objects with address and satoshis properties, in the order they should be paid:
    [
      { address: 'bchtest:qp965cur2a5e4g4y75zd6w356daeylp4q57c8swn7g', satoshis: 2000 }, // send this address 2000 satoshis first
      { address: 'bchtest:qz97n6fdve9ea92cxtwxqka572nsr9km9qu9u8ur6y', satoshis: 3000 }, // next send this address 3000 satoshis
      { address: 'bchtest:qqd7erps55s6tgz7rcsqg5rtj8djvnjcmg0ldpfxet', satoshis: 1700 }, // then send this address 1700 satoshis
      { address: 'bchtest:qrmefqlr5d50ts05ukpd4kr4due45hvusgjdsexmkx', satoshis: 'extra' }, // send this address any remaining satoshis
    ]
    							
    If you want all of the remaining satoshis to go to a particular address, either use that address last in the array, or set it's satoshis value to 'extra'.

callback_url (optional):

A valid url including protocol (http://, https://). There is no default value. This is the url you want us to send a post request to notify that a payment was received. If omitted we will not notify you of payments but we will still forward all payments to the forwarding address. If included, this url will be notified for every payment received at our response address. After 24 hours we drop the address and will no longer send notifications.

confirm (optional):

A 1 or 0. The default value is 0. This should be set to 1 if you do not want to be notified of payments until they are confirmed. If omitted or set to 0, you will be notified of payments immediately without waiting for confirmation. Waiting for confirmation can delay notification by 10 minutes or more.

testnet (optional):

The value should be a 1 or 0. The default value is 0. This should be set to 1 if you want to use testnet addresses and payments. This is useful for testing with testnet bitcoin cash instead of real bitcoin cash. If omitted or set to 0, livenet addresses and livenet payments are expected. Livenet addresses use real bitcoin cash.

Curl Examples

Testnet:

curl -H "Content-Type: application/json" -X POST -d '{
  "forwarding_address": "bchtest:qr3qdt8l70pzx74w3kvzm36zvrn3c77t0ver3xxhg8",
  "callback_url": "http://myurl.com/path/to/notify",
  "confirm": "0",
  "testnet": "1"
}' https://insticce.com/address

Livenet:

curl -H "Content-Type: application/json" -X POST -d '{
  "forwarding_address": "bitcoincash:qphrnewsvhh6rp96yvy0204xeljmgwtt5csf2gk86c",
  "callback_url": "http://myurl.com/path/to/notify",
  "confirm": "0",
  "testnet": "0"
}' https://insticce.com/address

Multiple addresses receiving payment percentages:

curl -H "Content-Type: application/json" -X POST -d '{
  "forwarding_address": {
	  'bchtest:qp965cur2a5e4g4y75zd6w356daeylp4q57c8swn7g': 40, // send this address 40% of each payment 
	  'bchtest:qz97n6fdve9ea92cxtwxqka572nsr9km9qu9u8ur6y': 30, // send this address 30% of each payment
	  'bchtest:qrmefqlr5d50ts05ukpd4kr4due45hvusgjdsexmkx': 28.7, // send this address 28.7% of each payment
	  'bchtest:qqd7erps55s6tgz7rcsqg5rtj8djvnjcmg0ldpfxet': 1.3, // send this address 1.3 % of each payment
	},
  "callback_url": "http://myurl.com/path/to/notify",
  "confirm": "0",
  "testnet": "0"
}' https://insticce.com/address

Multiple addresses receiving specific amounts:

curl -H "Content-Type: application/json" -X POST -d '{
  "forwarding_address": [
	  { address: 'bchtest:qp965cur2a5e4g4y75zd6w356daeylp4q57c8swn7g', satoshis: 2000 }, // send this address 2000 satoshis first
	  { address: 'bchtest:qz97n6fdve9ea92cxtwxqka572nsr9km9qu9u8ur6y', satoshis: 3000 }, // next send this address 3000 satoshis
	  { address: 'bchtest:qqd7erps55s6tgz7rcsqg5rtj8djvnjcmg0ldpfxet', satoshis: 1700 }, // then send this address 1700 satoshis
	  { address: 'bchtest:qrmefqlr5d50ts05ukpd4kr4due45hvusgjdsexmkx', satoshis: 'extra' }, // send this address any remaining satoshis
	],
  "callback_url": "http://myurl.com/path/to/notify",
  "confirm": "0",
  "testnet": "0"
}' https://insticce.com/address

NodeJs Example

const request = require('request'); // requires running npm install request

request({
  url: 'https://insticce.com/address',
  method: 'post',
  json: {
    forwarding_address: 'bchtest:qr3qdt8l70pzx74w3kvzm36zvrn3c77t0ver3xxhg8',
    callback_url: 'http://myurl.com/notify/path',
    testnet: 1,
    confirm: 0,
  },
}, function (err, result) {
  if (err) {
    console.log(err);
  } else {
    console.log(result.body);
  }
});

Response

address:

This is the unique BCH address in cash address format where your customers should send payments. Every payment we receive at this address, less the fee rate, will be sent to the forwarding address for 24 hours. After 24 hours we stop monitoring the address and it can be discarded.

price:

This is an estimate of the current bitcoin exchange price in USD. It can be helpful for estimating bitcoin due. We get our price estimates from a variety of sources depending on which sources are available at any given time. The price is not guaranteed in any way and is provided only as a courtesy.

Examples

Testnet:

{
  address: "bchtest:qqchtu8wf8wu5m7kse9fv5ur8ec0gaj6su53j4jn2d",
  price: 1012.93
}

Livenet:

{
  address: "bitcoincash:qphrnewsvhh6rp96yvy0204xeljmgwtt5csf2gk86c",
  price: 1010.13
}

Notifications

We monitor the address we gave you for 24 hours. We notify you of every payment that comes to the response address. The notifications are sent to the callback_url you provide in the address request.

method: POST

address:

This is the payment address we provided in response to /address requests.

amount:

This is how many bitcoins were paid.

satoshis:

This is the bitcoins paid shown in satoshis.

forwarding_address:

This is the address you provided us that we forwarded the payment to.

tx:

This is the transaction id to use to follow the payment on the block chain.

Examples

Testnet:

{
  "address": "bchtest:qzpllyjlxr2x2rdn488cv2qq2kmwe9kdsvh67q84lw",
  "amount": 0.0001,
  "satoshis": 10000,
  "forwarding_address": "bchtest:qp965cur2a5e4g4y75zd6w356daeylp4q57c8swn7g",
  "tx": "f8825cf25dc0a79a105bc34dadde016a41b36caca52f4550e48c0594805a1403"
}

Livenet:

{
  "address": "bitcoincash:qphrnewsvhh6rp96yvy0204xeljmgwtt5csf2gk86c",
  "amount": 0.00009863,
  "satoshis": 9863,
  "forwarding_address": "bitcoincash:qzjh2um6r3d5m4h2fsqvac8v3d50lt6v6qjr3gmsr2",
  "tx": "f83f8ca32f95f008812d1894d6505cf226a75aab5c66253ef1c7d0d4a282a8ed"
}

If your notification url is not responsive, because your web site is down or for any reason, we will continue to try to notify you at the url for at least 1 hour.

The payment is immediately forwarded to your forwarding_address regardless of notification status. There will never be a loss of funds even if you are experiencing technical problems at the callback url.

Questions and Comments

Don't hesistate to contact us with any questions or requests. We read and consider every customer request. The addition of multi-output payment forwarding was implemented because of one such request.