# 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);
})();
```


---

# Agent Instructions: 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:

```
GET https://docs.aiis.dev/developers/api/swaps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.