> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scriptonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana Integration

> Solana payment setup, token payments, Phantom/AppKit wallet, transaction flow, and troubleshooting.

## Solana Payment Setup

### 1. RPC

Use a private RPC in production. Scriptonia prefers Helius; other providers work if the URL is compatible.

Env (server):

```
HELIUS_RPC_URL=
# or
SOLANA_RPC_URL=
```

Public (client-safe):

```
NEXT_PUBLIC_SOLANA_RPC_URL=
NEXT_PUBLIC_SOLANA_NETWORK=mainnet
```

Priority: HELIUS\_RPC\_URL → SOLANA\_RPC\_URL → NEXT\_PUBLIC\_SOLANA\_RPC\_URL.\
If missing or invalid, it falls back to [api.mainnet-beta.solana.com](http://api.mainnet-beta.solana.com) or [api.devnet.solana.com](http://api.devnet.solana.com) based on NEXT\_PUBLIC\_SOLANA\_NETWORK.

***

### 2. Treasury

Payments are sent to the Treasury (agent) wallet:

```
TREASURY_WALLET=
```

Exposed to the client only as agentAddress via `GET /api/payment/config`.

***

### 3. Network

```
NEXT_PUBLIC_SOLANA_NETWORK=mainnet
# or
NEXT_PUBLIC_SOLANA_NETWORK=devnet
```

lib/solana.ts and the wallet use this for mainnet vs devnet.

***

## Token Mode

### Modes

| Mode            | Env                                    | Behavior                                                 |
| :-------------- | :------------------------------------- | :------------------------------------------------------- |
| SOL placeholder | USE\_SPL\_TOKEN not true or mint unset | Treated as SOL. Conversion: 0.02 SOL. Used for dev/test. |

***

### Balance and validation

**Server**

* getSOLTokenBalance(wallet)
* validatePayment(wallet, requiredSOL) in lib/solana.ts
* With SPL: uses the mint and associated token account
* Without: SOL × 2,750,000

**Client**

* PaymentForm uses `connection.getBalance(publicKey)`
* Fixed requiredSOL = 0.02 for the SOL placeholder UI
* For SPL, the client builds the tx via lib/solana-client.ts
* Balance checks for SPL are enforced on the server in `/api/payment` before the user is allowed to proceed

***

## Phantom / Reown AppKit

Scriptonia uses Reown AppKit with the Solana adapter for connect and signing. Phantom and other Solana wallets work through the same adapter.

***

### Config

**config/appkit.ts**

* projectId: NEXT\_PUBLIC\_REOWN\_PROJECT\_ID
* metadata: name, description, url, icons
* SolanaAdapter from `@reown/appkit-adapter-solana`

***

### Client

Hooks from:

* `@reown/appkit`
* `@reown/appkit-adapter-solana/react`

Used:

* useAppKitAccount
* useAppKitProvider
* useAppKitConnection

PaymentForm uses address, walletProvider, connection to:

* Resolve agentAddress from `GET /api/payment/config`
* Call createPaymentTransaction from lib/solana-client
* Sign and send via:
  * signAndSendTransaction
  * or signTransaction + sendRawTransaction
* `connection.confirmTransaction(signature, 'confirmed')`

Connect button and modal come from the AppKit/Reown UI. Phantom is selected when the user picks it in the wallet list.

***

## Transaction Flow

### 1. Payment (client)

* User connects wallet (AppKit → Phantom or other)
* PaymentForm gets agentAddress from `/api/payment/config`
* Balance:
  * SOL placeholder: `connection.getBalance(publicKey)`
  * User needs ≥ 0.02 SOL
* createPaymentTransaction(from, to, amountSOL) in lib/solana-client:
  * SOL: SystemProgram.transfer with 0.02 SOL
* User signs with wallet via AppKit
* `connection.confirmTransaction(signature, 'confirmed')`
* onPaymentConfirmed(signature, walletAddress)

***

### 2. Validation and Execute (server)

**POST /api/payment** (before the user sends the tx)

* validatePayment(userWalletPubKey) in lib/solana.ts (SOL-based)
* On success, workflow moves to payment\_processing

**POST /api/execute** (after the user pays)

* Body can include transactionSignature
* verifyTransaction(signature) in lib/solana.ts:
  * getSignatureStatus
  * must be err === null
  * must have a confirmation
* If valid:
  * execution runs
  * workflow updated with paymentDetails.transactionSignature

***

## Troubleshooting

**“Insufficient funds” (SOL)**

* Cause: SOL balance \< 0.02
* Fix: Use devnet and airdrop, or fund the wallet on mainnet

***

**“Balance fetch timed out” / RPC errors**

* Cause: RPC slow or RPC URL wrong or placeholder
* Fix: Set a valid RPC URL

***

**“Invalid agent address”**

* Cause: TREASURY\_WALLET missing or invalid
* Fix: Set TREASURY\_WALLET to a valid Solana public key
* `/api/payment/config` must return it as agentAddress

***

**“Wallet provider does not support transaction signing”**

* Cause: Wallet did not expose signAndSendTransaction or signTransaction
* Fix: Update Reown/AppKit and adapter; ensure wallet is unlocked and on the correct network

***

**“Invalid transaction signature” on Execute**

* Cause: verifyTransaction failed
* Fix: Ensure the user waits for confirmation and that client and server use the same network and RPC