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": "0x",
  "from": "0x7f23f9daf6e3a3a34bc53b2557d60179af5f2c71c7e586e0a8535e96bf335da3",
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "blockNumber": 29898055,
  "blockHash": "0x7f23f9daf6e3a3a34bc53b2557d60179af5f2c71c7e586e0a8535e96bf335da3",
}

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": 10.00
}

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": "0x",
  "from": "0x7f23f9daf6e3a3a34bc53b2557d60179af5f2c71c7e586e0a8535e96bf335da3",
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "blockNumber": 29898055,
  "blockHash": "0x7f23f9daf6e3a3a34bc53b2557d60179af5f2c71c7e586e0a8535e96bf335da3",
}

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

{
  "tokenQuantity": 9.50,
  "dollarValue": 9.50
}