Quick Start Guide

This guide demonstrates the complete flow of creating a token, distributing rewards and setting up liquidity.

Authentication

Some API requests require an API key passed with your request:

{
  "x-api-key": "YOUR_METAL_API_KEY"
}

To get an API key, simply Log in at metal.build and copy your API key in the dashboard.

1. Create a Token

First, create a token. You will only need to do this once for apps involving a single app-token.
Simply sign in at metal.build and click the Create Token button. If you want to create tokens from within your app please find more information in the Create a Token documentation

2. Get Token

Get comprehensive information about your token, including supply, holders, and other key metrics. Find more information in the Get Token Information documentation.

Required attributes: address - Address of your token.

const response = await fetch(
  'https://api.metal.build/token/0xa509df9bde9e283c4dd5fbaa68f5d5153fca364c',
)

const tokenInfo = await response.json()

{
 id: "0xa509df9bde9e283c4dd5fbaa68f5d5153fca364c",
 address: "0xa509df9bde9e283c4dd5fbaa68f5d5153fca364c",
 name: "MetalTestToken",
 symbol: "MTT",
 totalSupply: 1000000000,
 startingRewardSupply: 100000000,
 remainingRewardSupply: 49999800,
 merchantSupply: 50000000,
 merchantAddress: "0x5b9ccEf3F5BD6fA7c2102B874ea143432c9E175a",
 price: null,
 holders: [
   {
    id: "0x5b9ccef3f5bd6fa7c2102b874ea143432c9e175a",
    address: "0x5b9ccef3f5bd6fa7c2102b874ea143432c9e175a",
    balance: 50000000,
    value: 0,
  },
  {...
  }
 ]
}

3. Get Or Create Holder

Get Or Create holder wallets for your users to receive rewards. Each holder is created with a unique userId of your choice. Find more information in the Create Holder documentation.

Required attributes: userId - External ID for your holder (e.g., customer ID).

const response = await fetch('https://api.metal.build/holder/1234567890', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_METAL_API_KEY',
  },
})

const holder = await response.json()

{
  "success": true,
  "id": "1234567890",
  "address": "0x38A7ff01f9A2318feA8AafBa379a6c2c18b5d1dc",
  "totalValue": 0,
  "tokens": []
}

4. Distribute Rewards

Send tokens to users as rewards for engagement or achievements. Use this endpoint when you want to incentivize specific user actions or behaviors within your application. Find more information in the Send Rewards documentation.

Required attributes: address - Address of your token.

const response = await fetch(
  'https://api.metal.build/token/0xa509df9bde9e283c4dd5fbaa68f5d5153fca364c/reward',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_METAL_API_KEY',
    },
    body: JSON.stringify({
      sendTo: '0x743b2b90bB791028249d5F11054Ac58e45753a48',
      amount: 50,
    }),
  },
)

const reward = await response.json()

{ "success": true }