Carbon

Documentation

Welcome to Carbon's docs!

Get Started    

HTML Script & Custom URLs

HTML Script Overview

Apart from the 'environment' field and 'apikey' field, the only other major field a partner would likely change is the 'tokens' field (if enabled), which should be a comma-delimited list of tokens as a string (with no spaces). By default all tokens we support will be included. Check out this for the list of tokens we can support at the moment. We are aggressively expanding our crypto selection so stay tuned frequently for more crypto you may want to add to your integration!

Check out this section for more information on how to obtain an api key for our sandbox and production environments. Only 'sandbox' widgets are automatically authorized. To obtain production access check out this.

Reach out to gavin @ carbon.money & daniel @ carbon.money if you would like to discuss enabling more custom widget functionality or have any more questions.

Note that we only take the legacy api key (uuid) for the 'apikey' field at this time! The legacy api key is shown at the bottom of this dashboard screenshot below.

Custom URLs

Input Parameters

For the widget, you can add a few customized features including the types of cryptocurrencies you want to accept, the fiat currencies, and a button modal with custom text.

You have two methods of passing props.

1: You can setup your own widget from scratch using the steps below
2: (Easier and faster to setup) You can generate an iFrame using our url at https://buy.carbon.money. You can pass in parameters through the URL and add tokens and features easily. More on iFrame setup is available here.

Widget Size

Right now our current widget is at width 420px and height 550px. Some other sizes have not always worked for partners.

Example URL setup

https://buy.carbon.money/?tokens=trx,btt&homeScreenMessage=Play%20Tron%20Games&useModal=true&modalOpenText=Buy%20TRX

https://buy.carbon.money/?tokens=btc&receiveAddressBtc=1L3Nxg3JZeKgT5jBqAhDcb5HJAanqFh583

Input Parameters

Parameter
Access
Description

clientName

required & can append to URL

By default this will be Carbon Fiber. You can change this to whatever you like. The main place it will appear is when different wallets or providers connect to the user, upon which they will see clientName is asking to connect to your account.

environment

required

You must choose an environment in which your widget will render. Options are 'sandbox' or 'production'.

apiKey

required & can append to URL

You need a valid API key to use the widget. Please use the legacy API key! Make sure the legacy API key you insert matches the previously selected 'environment'.

tokens

optional & can append to URL

By default, you'll see all the tokens we have available. However you can narrow the list by adding a comma separated string of different coins you want to list. For example, if you want to show just ethereum and tron, you will use eth,trx.

homeScreenMessage

optional & can append to URL

By default, when the widget loads, you'll see a loading text of The API for fiat < > crypto. You can change this to something more pertinent for your users.

receiveAddress

optional & can append to URL, however, note that param is different when used in URL

In some cases (for example wallets or exchanges), you may already have a way of authenticating and/or registered addresses internally. You can pass in a variable or a constant for a deposit address in this optional object parameter. The address will autofill.

For URL params, options include receiveAddress + coin (first letter capitalized). For example: receiveAddressEth, receiveAddressEos, receiveAddressCusdeth.

For widget params, you need to pass in an object for receiveAddress. Each key-value pair will consist of a 'cryptocurrencySymbol' from our list of supported crypto and the value will be the blockchain address for that cryptocurrencySymbol. An example is below:

receiveAddress: {
btc: 'btcAddress',
eth: 'ethAddress'
}

targetContainerId

required

the widget needs a DOM element to fill in this the widget - targetContainerId sets the ID of the div to target.

darkTheme

optional (Boolean) can append to URL

Defaults to false.

Determines color theme, whether dark or light. Set to true or false

showSell

optional (Boolean) can append to URL

Defaults to true.

Determines whether or not to show 'Sell' as an option in widget.

currencies

optional (String) can append to URL

Default currency to display amounts in. Defaults to usd.

All supported country currencies available.

Ex: currencies: 'eur'

showCarbonLogo

option (Boolean)

true shows Carbon logo at the top of the widget. false shows generic "Buy Crypto" message

wrapCss

option (Boolean)

Set to true if you want to enforce our widget CSS just being applied within our widget. Otherwise our CSS may interfere with your CSS set elsewhere.

Note

The below code is meant to be a minimalistic example to get started with. If you copy/paste the below code and try to open it from your Finder, some functionality may not work as parts of our code check for either localhost or a whitelisted url. If you want to play around with our widget as quickly as possible, you can use node's http-server global module or python's http.server/SimpleHTTPServer to run an index.html file with the below code (substituting in your sandbox/production API key of course) on your localhost! Check this stack overflow question for more information: https://stackoverflow.com/questions/38497334/how-to-run-html-file-on-localhost.

For example, you can install the 'http-server' node package, save the below file (with your 'api key' and 'environment' updated) as index.html in a directory, run the http-server command in that directory, and then access the html file via localhost:8080.

Note that not only functionality but also styling will likely be messed up if you don't run the html file from localhost!

Feel free to play around with other HTML script variables (or url variables) apart from the required ones in the example below.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, shrink-to-fit=no"
    />
    <title>Carbon Fiber</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div
      class="carbonfiber"
      id="carbonfiber"
      style='display:flex;justify-content: center;align-items: center; height: 100%'
    >
    </div>
    <script type="text/javascript" src="https://d2xxy1rwbjzckp.cloudfront.net/carbonFiber.js.min.gz"></script>
    <script>
    	CarbonWidget.default.carbonFiber.render({
        clientName: "Carbon Fiber",
        environment: "production",
        apiKey: "8d761842-86d9-4e6e-ba21-dd9b9fg7ffda", // production
        targetContainerId: 'carbonfiber',
      });
    </script>
  </body>
</html>
  

Customizing Widget Confirmation Screen

We currently let you modify the widget confirmation screen by changing the button text and the redirect url.

default widget confirmation screen template

default widget confirmation screen template

Change Confirmation Button Text

POST

Now, you can customize the confirmation screen on the widget by changing the url of the button as well as the text! If you need to redirect users to a site, this is a perfect opportunity.

Pro Tip: You can get your current widgetText by just doing a GET call instead of a POST with no data passed in.

// legacy auth that will be deprecated in our v2 api
/*
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';
*/
// we strongly recommend using your secret key to more securely authenticate your superuser instead
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';

let url = `${ROOT}/v1/users/widgetText`;

let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
}

let data = {
  widgetText: "Go back to app"
}

axios.post(url, data, header).then(result => console.log(result)).catch(err => console.log(err));
{
   message: "successfully updated widgetText to Go back to app"
}

If you change the confirmation button's text, you may also want to change the URL the confirmation button is pointing to.

Again, you can do a GET to retrieve the current URL or POST to change the URL.

Change Confirmation Button URL

POST
// legacy auth that will be deprecated in our v2 api
/*
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';
*/
// we strongly recommend using your secret key to more securely authenticate your superuser instead
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';

let url = `${ROOT}/v1/users/widgetButtonURL`;

let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
}

let data = {
  widgetButtonURL: "https://app.com/cool_redirect"
}

axios.post(url, data, header).then(result => console.log(result)).catch(err => console.log(err));
{
   message: "successfully updated widgetButtonURL to https://app.com/cool_redirect"
}

Updated 5 days ago


What's Next

iFrame/Webview

HTML Script & Custom URLs


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.