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.


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

Was this page helpful?