Distribute Tokens

Endpoint: POST /token/:tokenAddress/distribute | Auth: 🔒 Secret Key | Purpose: Reward distribution

🤖 AI Implementation Summary:

Parameters: sendToAddress OR sendToId + amount (use only one address method)
Workflow: User action → trigger reward → call this endpoint → tokens distributed
Use Cases: Achievement rewards, welcome bonuses, marketing airdrops
Note: Requires token to have "Reward Allocation" enabled

Distribute tokens to your users on Base. This endpoint allows you to distribute tokens from your app balance to specified addresses.

POSTapi.metal.build/token/:tokenAddress/distribute

Distribute tokens

This endpoint initiates a token distribution.

🎁

AI Implementation Guide

Common workflow: User completes action → Your app calls this endpoint → Tokens distributed to user's wallet. Use sendToId with your internal user ID for simplicity, or sendToAddress if you have the wallet address.

Required attributes

To distribute tokens you must provide exactly one of either sendToAddress or sendToId, but not both.

Name
sendToAddress
Type
string
Description
The address of the user to receive the tokens. You can get the user's address from Get Holder.
Do not supply this if you are using sendToId.
Name
sendToId
Type
string
Description
The custom user ID that will be resolved to the user's wallet address.
Do not supply this if you are using sendToAddress.
Name
amount
Type
number
Description
The amount of tokens to send.

Request

POST

api.metal.build/token/:tokenAddress/distribute

const response = await fetch(
  'https://api.metal.build/token/0x1234567890abcdef1234567890abcdef12345678/distribute',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_SECRET_API_KEY',
    },
    body: JSON.stringify({
      sendToAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
      amount: 100
    }),
  }
)

const distribute = await response.json()

Response

{ "success": true }