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

# buildSolanaTransaction

> Builds an unsigned Solana transaction for native SOL or SPL token transfers via the Portal backend.

## Function Signature

```dart theme={null}
Future<PortalBuildSolanaTransactionResponse> buildSolanaTransaction({
  required String chainId,
  required String to,
  required String token,
  required String amount,
})
```

## Description

Builds an unsigned Solana transaction via the Portal backend. The returned `transaction` is a base64-encoded serialized Solana transaction ready to be signed and submitted using `portal.request(method: 'sol_signAndSendTransaction', ...)`.

## Parameters

| Parameter | Type     | Required | Description                                                                                                            |
| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `chainId` | `String` | Yes      | The chain ID in CAIP-2 format. Must start with `solana:` (e.g. `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for mainnet). |
| `to`      | `String` | Yes      | The recipient's Solana address (Base58).                                                                               |
| `token`   | `String` | Yes      | The asset symbol (`SOL`) for native transfers, or the SPL token mint address.                                          |
| `amount`  | `String` | Yes      | The human-readable amount (e.g. `"1"`, `"0.5"`). The backend converts to the token's smallest unit (lamports for SOL). |

## Returns

**`PortalBuildSolanaTransactionResponse`** — the serialized transaction plus metadata.

| Property      | Type                             | Description                                                                                |
| ------------- | -------------------------------- | ------------------------------------------------------------------------------------------ |
| `transaction` | `String`                         | A base64-encoded serialized Solana transaction. Pass this to `sol_signAndSendTransaction`. |
| `metadata`    | `PortalBuildTransactionMetadata` | Token info, formatted amounts, and the resolved sender / recipient addresses.              |
| `error`       | `String?`                        | Optional backend error message. Inspect this before submitting the transaction.            |

See [`buildEip155Transaction`](./buildeip155transaction#portalbuildtransactionmetadata) for the `PortalBuildTransactionMetadata` shape.

## Examples

### Native SOL transfer

```dart theme={null}
import 'package:portal_flutter/portal_flutter.dart';

final portal = Portal();

final response = await portal.buildSolanaTransaction(
  chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
  to: 'GxvUWHWwMpep8e6tXvVdaRmwEzKcUjhLYLhpXhS6wQtY',
  token: 'SOL',
  amount: '0.5',
);

if (response.error != null) {
  throw Exception('Failed to build transaction: ${response.error}');
}

print('Amount: ${response.metadata.amount} SOL');
print('From: ${response.metadata.fromAddress}');
print('To: ${response.metadata.toAddress}');
print('Serialized transaction: ${response.transaction}');
```

### SPL token transfer

```dart theme={null}
final response = await portal.buildSolanaTransaction(
  chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
  to: 'GxvUWHWwMpep8e6tXvVdaRmwEzKcUjhLYLhpXhS6wQtY',
  token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC mint
  amount: '100',
);

final symbol = response.metadata.tokenSymbol ?? 'Unknown';
print('Token: $symbol');
print('Mint: ${response.metadata.tokenAddress}');
print('Decimals: ${response.metadata.tokenDecimals}');
```

### Build, then sign and submit

```dart theme={null}
final built = await portal.buildSolanaTransaction(
  chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
  to: recipient,
  token: 'SOL',
  amount: '0.1',
);

if (built.error != null) {
  throw Exception(built.error);
}

final signResponse = await portal.request(
  chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
  method: 'sol_signAndSendTransaction',
  params: [built.transaction], // base64-encoded serialized transaction
);

// portal.request returns a PortalProviderResponse with String? result + String? error.
if (signResponse.error != null) {
  throw Exception('sol_signAndSendTransaction failed: ${signResponse.error}');
}

print('Solana signature: ${signResponse.result}');
```

## Errors

Throws a `PortalException` on failure:

| Code              | Description                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `NOT_INITIALIZED` | Portal was not initialized.                                                                                           |
| `BUILD_FAILED`    | The backend could not build the transaction (insufficient SOL for rent / fees, unsupported token, invalid recipient). |

```dart theme={null}
try {
  final response = await portal.buildSolanaTransaction(
    chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
    to: recipient,
    token: 'SOL',
    amount: '0.1',
  );
} on PortalException catch (e) {
  print('Build failed: ${e.code} - ${e.message}');
}
```

Always also check `response.error` for soft failures from the backend.

## Implementation Notes

* `amount` is the **human-readable** value. Pass `"1"` for 1 SOL, not `"1000000000"` lamports.
* For native transfers, use `"SOL"`. For SPL tokens, use the mint address.
* The Portal backend automatically creates the recipient's Associated Token Account (ATA) for SPL transfers when needed — the resulting `transaction` already includes the ATA-creation instruction.
* `chainId` must start with `solana:`. Use [`buildEip155Transaction`](./buildeip155transaction) for EVM chains.

## Related

* [buildEip155Transaction](./buildeip155transaction)
* [request](./request)
* [sendTransaction](./sendtransaction)
* [Sign a transaction guide](../guide/sign-a-transaction)