Buy Tokens
Buy ERC20 tokens from a holder's account with USDC.
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
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.
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
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.
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
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.
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
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).