Wallet

V 2.0

FORWARDING and SAVING wallets

Bitcoin QR code icon

Contents

You can create a lot of wallets for your project. Each wallet can be one of these types: Forwarding or Saving.

Forwarding wallet accept and immediately forward payment to your wallet. Also, it has the ability to split forwarding payment.

Income payment can be split to list up to 255 addresses. These receivers will get part in exact specified amount or by percent (quota) from income amount. It's a very convenient way to immediately pay to referral, for multi-level marketing, receive a royalty, split to cold storage and hot wallet from all income payments. In the case of the specified amount, the rest will be sent to the last address.

Each payment is divided by the order of the list until the last Satoshi. Payouts are made on the list from the first to the last. The order of the list is important.

Saving wallet accumulates all income payments and can be transferred to one or more receivers. You can use from 1 to 255 destination addresses with splitting rule.

Simple requests:

{
"type": "saving|forwarding",
"callback":{                       #optional
      "url": "your_callback_URL",  #optional
      "data":{                     #optional
         "optional_key": "value"
      }
   },
	"destinations":[           #Destinations for Forwarding wallet type only
      {"amount": <amount|"percents">, "address": "<bitcoin_address>"},
		... #from 1 to 255 addresses
	]
}

Code Example for wallet type

Callback URL KeyValue

+

AddressAmount

+


{
   "type": "forwarding",
   "callback":{
      "url" :  "http://example.com/callback"
   }
}
  
<?php
  $json_data = array (
    'type' => "forwarding",
    'callback' => array(
        'url'=> "http://example.com/callback"
    )
  );
  
  $api_endpoint = "https://apirone.com/api/v2/btc/wallet";
 
  $curl = curl_init($api_endpoint);
  curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
  curl_setopt($curl, CURLOPT_POST, 1);
  curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($json_data));
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
  $response = curl_exec($curl);
  $http_status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  curl_close($curl);
 
  if ($http_status_code==200){
	  $decoded = json_decode($response, true);
	  echo "Wallet: " . $decoded["wallet"] . "<BR>";
	  echo "Key: " . $decoded["transfer_key"];
  } else {
      var_dump($response);
  }
?>
Send request
Response from server:

JSON Schema description

Use POST string request containing the object in JSON format.

Callback URL

Callback is an array of callback URL and user's Data parameters.

Parameter Description Required
{callback:url}
string,
=< 1024 chars

Callback URL
Your server's callback URL to receive data about the payment. This must be a valid URL.

Required
{callback:data}
array

Data
The associative array is based on key-value pairs. You can use as additional identification or secure a generated bitcoin address.

For example 'secret' = '7j0ap91o99cxj8k9' or 'invoice_id'='1234'

Optional

Destination address and amount

Your destination(s) bitcoin address(es) where confirmed payments will be forwarded. Minimum 1, maximum 255 destination address.

Parameter Description Required Examples
{destinations}
string,
32 - 42 chars
Destination address

Your destination bitcoin address where confirmed payments will be forwarded.

Required

1apiKcJM95jENZeom2dQo8ShK7dUQkRaS

bc1qggg2ys8duv4qvnfgzng2p75m6ehklcmfygr9m4

{amount}
(integer | "percent in string")

Amount

An amount in Satoshi or in percent. This parameter may be missing or empty. In this case, the rest amount will be forwarded there.

Optional

253999

"20%"

"31.55%"

Success response:

{
  "wallet": "8e9c53a62755bcc66e4d2aaae3a2af6d",
  "type": "saving",
  "transfer_key": "7j0ap91o99cxj8k97j0ap91o99cxj8k9",
  "currency": "btc",
  "callback":
  {
     "url": "http://example.com/callback",
     "data":
     {
        "invoice_id": "1234",
        "secret": "7j0ap91o99cxj8k9",
     }
  }
}

Error Response

Error response return messages in plain text format below:
Wrong parameters.
Destinations couldn't be empty.
All destinations should be unique.
'destinations' attribute is required for forwarding wallet type.
Invalid wallet type. Valid wallet types are: saving,forwarding,forwarding-legacy.
Invalid address: mqTZ5Lmt1rrgFPeGeTC8DFExAxV1U852G.
Incorrect amount for address 'tb1q8j9amkk2urc8cs2x94l80p7c2dnxcmmxgxr3n8'.

Cases of split payment

Example with splitting to exact amounts:

The Store pays a fixed amount of 0.2 BTC to Referral, 0.3 BTC for Delivery, 1.5 BTC hold for future in Cold Storage and rest keep in Business.

{
   "callback":{
      "url":"http://example.com/callback",
      "data":{
         "secret":"7j0ap91o99cxj8k9"
      }
   },
   "destinations":[
      {"address": "1apiKcJM95jENZeom2dQo8ShK7dUQkRaS", "amount":  20000000},
      {"address": "1apimr7q2cL3xPma8SfiDPyTdWSHXSEyB", "amount":  30000000},
      {"address": "1ApiwpetcWnBbkpU7cb7biPfc6Tiucasf8", "amount": 150000000},
      {"address": "1Api8ZyHPp4f1QNTsi3AGyXbaTnzzAuDez"}
   ]
}

The Buyer pays for order 10 BTC.

Case: paid less. If the Buyer pays 1 BTC only, then the amount will be split to 0.2, 0.3 and rest 1 - 0.5 = 0.5 will be sent to Cold Storage. The Business address will not receive anything because not enough amount to transfer.

Case: paid enough. The Store receives notification about payment and arrived amount split to specified amounts for different Bitcoin addresses: 0.2, 0.3, 1.5 and rest 10 - 2 = 8 BTC goes to business.

Case: overpaid. The last address (without amount) in the list will receive the rest amount.

Network fee and service fee will be deducted from the last address. It this case deduct from a Business part.

Example with splitting by percent:

Let's imagine that you are The Exchanger. You would like to cut 20 percents to Hot Wallet (for future fast payout to customers), 30 percents for the Management or arbitrage, and 50 percents to a safe place - Cold Storage.

{
   "callback":{
      "url":"http://example.com/callback",
      "data":{
         "secret":"7j0ap91o99cxj8k9"
      }
   },
   "destinations":[
      {"address": "1apiKcJM95jENZeom2dQo8ShK7dUQkRaS", "amount": "20%"},
      {"address": "1apimr7q2cL3xPma8SfiDPyTdWSHXSEyB", "amount": "30%"},
      {"address": "1ApiwpetcWnBbkpU7cb7biPfc6Tiucasf8"}
   ]
}

The order of addresses in the list does not matter. The total sum must be 100 percents.
Whole income payment is divided into these three addresses proportionally.
Network fee and transaction fee will be deducted first.