> For the complete documentation index, see [llms.txt](https://docs.aiis.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aiis.dev/developers/api/swaps.md).

# Swaps

This explains how to use the aiis.dev swap endpoint for preparing unsigned Solana transactions to swap tokens using our bonding curve. The route supports two operations: a **buy** swap (wrapping SOL into WSOL and executing a buy instruction) and a **sell** swap (executing a sell instruction and cleaning up WSOL).

***

### How It Works

1. **Account Setup and Preparation**
   * **Associated Token Accounts**: The route derives and, if necessary, creates the user’s WSOL and target token accounts.
   * **WSOL Account Top-Up and Sync**: For buy operations, the code calculates whether additional lamports (including a fee buffer) are needed to top up the WSOL account and then syncs the account to update its wrapped SOL balance.
   * **Tip Transfer**: A jito tip transfer instruction is added at the start to send a small fee for faster landing.
   * **Bonding Curve Instruction**: Depending on the route ("buy" or "sell"), the corresponding bonding curve instruction is appended.
   * **Cleanup**: For sell operations, the WSOL account is closed after the swap.
2. **Transaction Building**
   * All instructions are assembled into a versioned transaction.
   * The transaction is serialized to a base64-encoded string and returned to the client for signing. The server never signs transactions, ensuring that private keys remain secure on the client side.

***

### How to Use

#### Endpoint

* **Method:** POST
* **Path:** `/swap/prepare`

#### Request Payload Schema

```json
{
  "route": "buy" or "sell",
  "lamports": "<amount as string>",
  "mint": "<token mint address>",
  "userPublicKey": "<user's wallet public key>"
}
```

* **route**: Specifies the swap type. Use `"buy"` for buying tokens or `"sell"` for selling.
* **lamports**: The amount (in lamports) involved in the swap, provided as a string.
* **mint**: The mint address of the token being swapped.
* **userPublicKey**: The user's wallet public key.

#### Example Request:

```json
curl -X POST https://api.aiis.dev/v2/swap/prepare \
-H "Content-Type: application/json" \
-d '{
  "route": "buy",
  "lamports": "1000000",
  "mint": "So11111111111111111111111111111111111111112",
  "userPublicKey": "YourPublicKeyHere"
}'
```

#### Example Response:

```json
{
  "unsignedTx": "BASE64_ENCODED_TRANSACTION_STRING"
}
```

* **unsignedTx**: This is the unsigned versioned transaction encoded in base64. The client is expected to sign this transaction before submitting it to the blockchain.

### Integration:

```javascript
import axios from "axios";
import { Connection, VersionedTransaction, Keypair, clusterApiUrl } from "@solana/web3.js";
import { readFileSync } from "fs";

(async () => {
  // Load private key from file (ensure this file is secured!)
  const secret = JSON.parse(readFileSync("path/to/secret-key.json", "utf8"));
  const keypair = Keypair.fromSecretKey(new Uint8Array(secret));

  // Define parameters for the swap
  const API_URL = "https://api.aiis.dev/v2/swap/prepare"; // Your swap route endpoint
  const params = {
    route: "buy",
    lamports: "1000000", // Amount in lamports as a string
    mint: "TokenMintPublicKeyHere",
    userPublicKey: keypair.publicKey.toBase58(),
  };

  // Fetch unsigned transaction from the swap route
  const { data: { unsignedTx } } = await axios.post(API_URL, params);
  if (!unsignedTx) throw new Error("No unsigned transaction returned");

  // Deserialize and sign the transaction
  const tx = VersionedTransaction.deserialize(Buffer.from(unsignedTx, "base64"));
  await keypair.signTransaction(tx);

  // Send the signed transaction
  const connection = new Connection(clusterApiUrl("devnet"), "processed");
  const txId = await connection.sendRawTransaction(tx.serialize());
  console.log("Transaction sent, txid:", txId);
})();
```