<!-- LLM_VERSION_INFO
FORMAT: text/markdown
CONTENT_TYPE: article
ORIGINAL_URL: https://www.carbon.money/docs-sub/docs/html-script
ALTERNATE_VERSION: docs-sub/docs/html-script/index.html (text/html)
EXTRACTION_DATE: 2026-06-11T01:45:16.780Z

This is the markdown version with text-only content (images converted to alt-text).
For rich formatting with images, request the HTML version at: docs-sub/docs/html-script/index.html
-->

# HTML Script Overview

You can setup your own widget HTML from scratch via a JS script or embed our custom URL in an iFrame to integrate our widget.

A partner must set the 'publicKey' field for authentication if you're integrating the HTML script or custom URL. A partner must also set the 'environment' field and 'targetContainerId' field if you're integrating the HTML script.

One other major field a partner may change includes the 'tokens' field (if enabled), a comma-delimited list of tokens as a string (with no spaces). By default all tokens we support will be included. Check out [this](/content/docs-sub/docs/cryptocurrencies#section-overview/index.html) 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!

Several other major fields a partner may integrate includes the 'currencies' field (the base settlement currency for the purchase--options are 'usd', 'eur', and 'gbp'), the 'amount' field (the base purchase amount), and the 'receiveAddress' field. More on all of these parameters later.

Check out [this section](/content/site-root.html) for more information on how to create a developer account and obtain credentials. Only 'sandbox' widgets are automatically authorized. To obtain production access check out [this](/content/docs-sub/docs/going-live/index.html).

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 you used to only be able authenticate via the legacy 'apikey' field, which involved your superuser UUID. That should be secret and never publicly exposed so we instead strongly recommend superusers to authenticate via their 'publicKey'. The public key is shown at the top of the bottom screenshot. You can access the api keys either from your dashboard account home ('Production/Sandbox Publishable Key') or from the Developers -> Api Key section in your left tab (below screenshot). We will deprecate legacy api key authentication on May 20, 2020. Please reach out to [email protected] if you have any questions or concerns.

# Custom URLs

### Input Parameters

You can generate an iFrame using a custom url working off of the root base url [https://buy.carbon.money](/content/site-root.html). You can pass in parameters through the URL and add tokens and features easily. More on iFrame setup is available [here](/content/docs-sub/docs/iframe/index.html).

### 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=btc&receiveAddressBtc=1L3Nxg3JZeKgT5jBqAhDcb5HJAanqFh583&amount=10¤cies=usd](/content/site-root.html)

\` [https://buy.carbon.money/?tokens=trx,btt&homeScreenMessage=Play%20Tron%20Games](/content/site-root.html)

### Credit/Debit API Overview

You may find it helpful to peruse our Credit/Debit API docs to contextualize your widget integration: [https://docs.carbon.money/docs/credit-debit](/content/docs-sub/docs/credit-debit/index.html)

## 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'. If you want to integrate our production widget using a custom URL, choose [https://buy.carbon.money](/content/site-root.html) as your root. In sandbox, use [https://buysandbox.carbon.money](/content/site-root.html) |
| apiKey (DEPRECATED) | was 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'.|
| publicKey           | required & **can append to URL** | You need a valid public key to use the widget. Make sure the public 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 registering 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) following the camelcase convention. For example: `receiveAddressEth`, `receiveAddressEos`.  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](/content/docs-sub/docs/cryptocurrencies/index.html) 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.                                                        |
| currencies          | optional (String) **can append to URL**            | Default settlement currency to display amounts in. Defaults to usd. The available settlement currencies are 'usd', 'eur' and 'gbp'.| 
| amount              | optional (String) **can append to URL**             | Default base amount for purchase. If not specified, the default base amount will be `5`. You should specify an amount of at least $5 (or the equivalent if you're specifying a settlement currency that is not USD) as our current minimum base purchase amount is $5.|
| showCarbonLogo      | option (Boolean)                  | true shows Carbon logo at the top of the widget. false shows generic "Buy Crypto" message                                                                                          |

### 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](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.

- [HTML](/content/docs-sub/docs/html-script/index.html)

```
<!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",
        publicKey: "pk_live_jK3kaJ1kp83e16Pn37w9WkpQ", // 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.

## 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.

- [JavaScript](/content/docs-sub/docs/html-script/index.html)
- [Success (200)](/content/docs-sub/docs/html-script/index.html)

```javascript
// 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));
```

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

- [JavaScript](/content/docs-sub/docs/html-script/index.html)
- [Success (200)](/content/docs-sub/docs/html-script/index.html)

Updated 5 days ago

* * *

### What's Next

|     |
| --- |
| [iFrame/Webview](/content/docs/iframe/index.html) |