> For the complete documentation index, see [llms.txt](https://docs.heyhal.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heyhal.xyz/api-documentation/swap-tokens.md).
# Swap Tokens
## Swap Token
Endpoint: POST /api/v1/coin/swap
### Description
This endpoint generates a serialized transaction for token swaps (buy/sell) on the platform. It handles both initial minting with buys and regular trading operations. The endpoint returns a serialized transaction that must be signed and sent by the client.
**Authentication Required:** Yes
**Type:** Bearer Token (JWT)
**Request Headers**
**Content-Type:** application/json
**Authorization:** Bearer \
**Body Parameters**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| token | string | Yes | The mint address of the token |
| amount | string | Yes | The amount to swap in lamports |
| type | string | Yes | The type of swap ("buy" or "sell") |
| memo | string | No | Optional memo for tracking referrals and bonuses |
**Example Request Body:**
{
"token": "TokenMintAddress123...",
"amount": "1000000000",
"type": "buy",
"memo": "home"
}
**Response**
Success Response:
Status Code: 200 OK
Content-Type: application/json
{
"serializedTransaction": "base58EncodedSerializedTransaction..."
}
**Error Response:**
Status Code: 500 Internal Server Error
{
"error": "An internal error occurred. Please try again later."
}
**Example Usage:**
async function swapToken(
tokenMintAddress: string,
amount: string,
type: 'buy' | 'sell',
memo?: string
) {
try {
const response = await fetch('', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': \`Bearer ${jwt}\`
},
body: JSON.stringify({
token: tokenMintAddress,
amount,
type,
memo
})
});
if (!response.ok) {
throw new Error(\`HTTP error! status: ${response.status}\`);
}
const { serializedTransaction } = await response.json();
// Sign and send transaction using wallet
const signedTx = await wallet.signTransaction(
Transaction.from(bs58.decode(serializedTransaction))
);
const signature = await connection.sendRawTransaction(
signedTx.serialize()
);
return signature;
} catch (error) {
console.error('Error in swap operation:', error);
throw error;
}
}
### Implementation Notes
Transaction Flow -
#### For buy operations:
If token is not minted, creates mint + buy transaction
If token exists, creates buy transaction only
**For sell operations:**
Creates sell transaction
**Memo Usage:**
Memos are included in the transaction for tracking
Used internally for referral points and bonus calculations
Visible on-chain for transaction tracking
**Transaction Handling:**
Returns serialized transaction only
Client must sign and send the transaction
All necessary instructions are bundled in single transaction
**Best Practices:**
Always verify transaction before signing
Implement proper error handling
Consider price impact for large swaps
Handle network congestion gracefully
**Related Operations:**
Use GET /api/v1/coin/reserves to check liquidity before swap
Monitor transaction status after sending
Consider implementing retry logic for failed transactions