Buy Tokens

Buy ERC20 tokens from a holder's account with USDC.

POSTapi.metal.build/holder/:holderId/buy

Buy Tokens

Required attributes

Name
tokenAddress
Type
string
Description
The address of the token to buy.
Name
usdcAmount
Type
number
Description
The USDC amount to spend (e.g., 1 for $1).

Optional attributes

Name
swapFeeBps
Type
number
Description
Fee in basis points (e.g., 1000 = 10%).

Request

POST

api.metal.build/holder/:userId/buy

const response = await fetch(
  'https://api.metal.build/holder/holder_1/buy',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_SECRET_API_KEY',
    },
    body: JSON.stringify({
      tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',
      usdcAmount: 10,
      swapFeeBps: 1000,
    }),
  }
)

const tx = await response.json()

Response

{
  "success": true,
  "status": "completed",
  "transactionHash": "0x123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234",
  "from": "0x1234567890abcdef1234567890abcdef12345678",
  "to": "0x0000000000000000000000000000000000000000",
  "tokenAddress": "0x191d25c061C081583E616d8978eA670f45A803E5",
  "blockNumber": 29898055,
  "blockHash": "0x7f23f9daf6e3a3a34bc53b2557d60179af5f2c71c7e586e0a8535e96bf335da3",
  "gasUsed": "150000",
  "effectiveGasPrice": "20000000000",
  "sellAmount": 10,
  "buyAmount": 1500.75,
  "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "buyToken": "0x191d25c061C081583E616d8978eA670f45A803E5"
}

Response attributes

Name
success
Type
boolean
Description
Indicates if the transaction was successful.
Name
status
Type
string
Description
Transaction status (completed, pending, failed).
Name
transactionHash
Type
string
Description
The transaction hash on the blockchain.
Name
sellAmount
Type
number
Description
Amount of USDC spent.
Name
buyAmount
Type
number
Description
Amount of tokens received.
Name
sellToken
Type
string
Description
USDC token address.
Name
buyToken
Type
string
Description
Purchased token address.

GETapi.metal.build/holder/:holderId/buy/quote

Get Buy Quote

Get a quote for token purchase without executing the transaction.

Required attributes

Name
tokenAddress
Type
string
Description
The address of the token to buy.
Name
usdcAmount
Type
number
Description
The USDC amount to spend (e.g., 1 for $1).

Optional attributes

Name
swapFeeBps
Type
number
Description
Fee in basis points (e.g., 1000 = 10%).

Request

GET

api.metal.build/holder/:userId/buy/quote

const response = await fetch(
  'https://api.metal.build/holder/holder_1/buy/quote',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_SECRET_API_KEY',
    },
    body: JSON.stringify({
      tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',
      usdcAmount: 10,
      swapFeeBps: 1000,
    }),
  }
)

const price = await response.json()

Response

{
  "tokenQuantity": 1500.75,
  "dollarValue": 9.85
}

Response attributes

Name
tokenQuantity
Type
number
Description
The amount of tokens you will receive for the specified USDC amount.
Name
dollarValue
Type
number
Description
The actual dollar value of tokens received (may differ slightly due to price impact and fees).

Sell Tokens

Sell ERC20 tokens from a holder's account for USDC.

POSTapi.metal.build/holder/:holderId/sell

Sell Tokens

Required attributes

Name
tokenAddress
Type
string
Description
The address of the token to sell.
Name
tokenAmount
Type
number
Description
The amount of tokens to sell.

Optional attributes

Name
swapFeeBps
Type
number
Description
Fee in basis points (e.g., 1000 = 10%).

Request

POST

api.metal.build/holder/:userId/sell

const response = await fetch(
  'https://api.metal.build/holder/holder_1/sell',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_SECRET_API_KEY',
    },
    body: JSON.stringify({
      tokenAddress: '0xb488fcb23333e7baa28d1dfd7b69a5d3a8bfeb3a',
      tokenAmount: 100,
      swapFeeBps: 1000,
    }),
  }
)

const tx = await response.json()

Response

{
  "success": true,
  "status": "completed",
  "transactionHash": "0xabcdef123456789abcdef123456789abcdef123456789abcdef123456789abc",
  "from": "0x1234567890abcdef1234567890abcdef12345678",
  "to": "0x0000000000000000000000000000000000000000",
  "tokenAddress": "0xb488fcb23333e7baa28d1dfd7b69a5d3a8bfeb3a",
  "blockNumber": 29898056,
  "blockHash": "0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
  "gasUsed": "160000",
  "effectiveGasPrice": "21000000000",
  "sellAmount": 100,
  "buyAmount": 9.5,
  "sellToken": "0xb488fcb23333e7baa28d1dfd7b69a5d3a8bfeb3a",
  "buyToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}

Response attributes

Name
success
Type
boolean
Description
Indicates if the transaction was successful.
Name
status
Type
string
Description
Transaction status (completed, pending, failed).
Name
transactionHash
Type
string
Description
The transaction hash on the blockchain.
Name
sellAmount
Type
number
Description
Amount of tokens sold.
Name
buyAmount
Type
number
Description
Amount of USDC received.
Name
sellToken
Type
string
Description
Sold token address.
Name
buyToken
Type
string
Description
USDC token address.

Token Lock Restrictions: If you have locked tokens from presale purchases, only your unlocked balance is available for selling. Attempting to sell more than your available balance will result in an error showing your locked amount and unlock date.

GETapi.metal.build/holder/:holderId/sell/quote

Get Sell Quote

Get a quote for token sale without executing the transaction.

Required attributes

Name
tokenAddress
Type
string
Description
The address of the token to sell.
Name
tokenAmount
Type
number
Description
The amount of tokens to sell.

Optional attributes

Name
swapFeeBps
Type
number
Description
Fee in basis points (e.g., 1000 = 10%).

Request

GET

api.metal.build/holder/:userId/sell/quote

const response = await fetch(
  'https://api.metal.build/holder/holder_1/sell/quote',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_SECRET_API_KEY',
    },
    body: JSON.stringify({
      tokenAddress: '0xb488fcb23333e7baa28d1dfd7b69a5d3a8bfeb3a',
      tokenAmount: 100,
      swapFeeBps: 1000,
    }),
  }
)

const price = await response.json()

Response

{
  "usdcAmount": 9.50,
  "dollarValue": 9.50
}

Response attributes

Name
usdcAmount
Type
number
Description
The amount of USDC you will receive for selling the specified token amount.
Name
dollarValue
Type
number
Description
The dollar value of the USDC received (should match usdcAmount).