> ## 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.

# buildEip155Transaction

> Builds an unsigned EIP-155 transaction for Ethereum-compatible chains, with gas, value, and data populated by the Portal backend.

## Function Signature

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

## Description

Builds an unsigned EIP-155 transaction via the Portal backend. The returned payload is ready to be signed and submitted using `portal.request(method: 'eth_sendTransaction', ...)`.

## Parameters

| Parameter | Type     | Required | Description                                                                                                            |
| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `chainId` | `String` | Yes      | The chain ID in CAIP-2 format. Must start with `eip155:` (e.g. `eip155:1` for mainnet, `eip155:11155111` for Sepolia). |
| `to`      | `String` | Yes      | The recipient address (`0x…`).                                                                                         |
| `token`   | `String` | Yes      | The asset symbol (e.g. `ETH`) for native transfers, or the ERC-20 token contract address.                              |
| `amount`  | `String` | Yes      | The human-readable amount (e.g. `"0.001"`, `"100"`). The backend converts this to the token's smallest unit.           |

## Returns

**`PortalBuildEip155TransactionResponse`** — the unsigned transaction plus metadata.

| Property      | Type                             | Description                                                                     |
| ------------- | -------------------------------- | ------------------------------------------------------------------------------- |
| `transaction` | `PortalEip155Transaction`        | The unsigned transaction payload to pass to `eth_sendTransaction`.              |
| `metadata`    | `PortalBuildTransactionMetadata` | Token info, formatted amounts, and the resolved sender / recipient addresses.   |
| `error`       | `String?`                        | Optional backend error message. Inspect this before submitting the transaction. |

### PortalEip155Transaction

| Property | Type      | Description                                                         |
| -------- | --------- | ------------------------------------------------------------------- |
| `from`   | `String`  | The sender address (the Portal wallet's EVM address).               |
| `to`     | `String`  | The destination address.                                            |
| `data`   | `String?` | Optional hex-encoded calldata (populated for ERC-20 transfers).     |
| `value`  | `String?` | Optional hex-encoded value in wei (populated for native transfers). |

### PortalBuildTransactionMetadata

| Property        | Type      | Description                                               |
| --------------- | --------- | --------------------------------------------------------- |
| `amount`        | `String`  | Formatted (human-readable) amount.                        |
| `fromAddress`   | `String`  | Sender address.                                           |
| `toAddress`     | `String`  | Recipient address.                                        |
| `tokenAddress`  | `String?` | ERC-20 contract address (null for native transfers).      |
| `tokenDecimals` | `int`     | Token decimals.                                           |
| `tokenSymbol`   | `String?` | Token symbol when known.                                  |
| `rawAmount`     | `String`  | Amount in the token's smallest unit (wei for native ETH). |

## Examples

### Native ETH transfer

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

final portal = Portal();

final response = await portal.buildEip155Transaction(
  chainId: 'eip155:11155111', // Sepolia
  to: '0x1234567890123456789012345678901234567890',
  token: 'ETH',
  amount: '0.001',
);

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

final symbol = response.metadata.tokenSymbol ?? 'ETH';
print('From: ${response.transaction.from}');
print('To: ${response.transaction.to}');
print('Value (wei): ${response.transaction.value}');
print('Amount: ${response.metadata.amount} $symbol');
```

### ERC-20 token transfer

```dart theme={null}
final response = await portal.buildEip155Transaction(
  chainId: 'eip155:1',
  to: '0x1234567890123456789012345678901234567890',
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  amount: '100',
);

final symbol = response.metadata.tokenSymbol ?? 'Unknown';
print('Token: $symbol');
print('Token contract: ${response.metadata.tokenAddress}');
print('Calldata: ${response.transaction.data}');
print('Raw amount: ${response.metadata.rawAmount}');
```

### Build, then sign and submit

`buildEip155Transaction` only constructs the transaction — pass the result to `request` to actually sign and broadcast it:

```dart theme={null}
final built = await portal.buildEip155Transaction(
  chainId: 'eip155:1',
  to: recipient,
  token: 'ETH',
  amount: '0.01',
);

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

final txResponse = await portal.request(
  chainId: 'eip155:1',
  method: 'eth_sendTransaction',
  params: [
    {
      'from': built.transaction.from,
      'to': built.transaction.to,
      if (built.transaction.value != null) 'value': built.transaction.value,
      if (built.transaction.data != null) 'data': built.transaction.data,
    },
  ],
);

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

print('Transaction hash: ${txResponse.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 funds, unsupported token, invalid recipient). |

```dart theme={null}
try {
  final response = await portal.buildEip155Transaction(
    chainId: 'eip155:1',
    to: recipient,
    token: 'ETH',
    amount: '0.01',
  );
} on PortalException catch (e) {
  print('Build failed: ${e.code} - ${e.message}');
}
```

Always also check `response.error` — the backend may signal a soft failure (e.g. a non-fatal warning about insufficient balance) without throwing.

## Implementation Notes

* `amount` is the **human-readable** value. The Portal backend handles decimal conversion based on the token. Pass `"0.001"` for 0.001 ETH, not `"1000000000000000"`.
* For native transfers, use the symbol `"ETH"` (or the chain's native symbol). For tokens, use the contract address.
* `chainId` must start with `eip155:`. Use [`buildSolanaTransaction`](./buildsolanatransaction) for Solana.

## Related

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