> 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
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.heyhal.xyz/api-documentation/swap-tokens.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.