Fixes for build

Reviewed-on: #186

api/gateway/chain/client/client.go

@@ -24,6 +24,8 @@ type Client interface {
 	GetTransfer(ctx context.Context, req *chainv1.GetTransferRequest) (*chainv1.GetTransferResponse, error)
 	ListTransfers(ctx context.Context, req *chainv1.ListTransfersRequest) (*chainv1.ListTransfersResponse, error)
 	EstimateTransferFee(ctx context.Context, req *chainv1.EstimateTransferFeeRequest) (*chainv1.EstimateTransferFeeResponse, error)
+	ComputeGasTopUp(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) (*chainv1.ComputeGasTopUpResponse, error)
+	EnsureGasTopUp(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) (*chainv1.EnsureGasTopUpResponse, error)
 	Close() error
 }
 
@@ -36,6 +38,8 @@ type grpcGatewayClient interface {
 	GetTransfer(ctx context.Context, in *chainv1.GetTransferRequest, opts ...grpc.CallOption) (*chainv1.GetTransferResponse, error)
 	ListTransfers(ctx context.Context, in *chainv1.ListTransfersRequest, opts ...grpc.CallOption) (*chainv1.ListTransfersResponse, error)
 	EstimateTransferFee(ctx context.Context, in *chainv1.EstimateTransferFeeRequest, opts ...grpc.CallOption) (*chainv1.EstimateTransferFeeResponse, error)
+	ComputeGasTopUp(ctx context.Context, in *chainv1.ComputeGasTopUpRequest, opts ...grpc.CallOption) (*chainv1.ComputeGasTopUpResponse, error)
+	EnsureGasTopUp(ctx context.Context, in *chainv1.EnsureGasTopUpRequest, opts ...grpc.CallOption) (*chainv1.EnsureGasTopUpResponse, error)
 }
 
 type chainGatewayClient struct {
@@ -139,6 +143,18 @@ func (c *chainGatewayClient) EstimateTransferFee(ctx context.Context, req *chain
 	return c.client.EstimateTransferFee(ctx, req)
 }
 
+func (c *chainGatewayClient) ComputeGasTopUp(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) (*chainv1.ComputeGasTopUpResponse, error) {
+	ctx, cancel := c.callContext(ctx)
+	defer cancel()
+	return c.client.ComputeGasTopUp(ctx, req)
+}
+
+func (c *chainGatewayClient) EnsureGasTopUp(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) (*chainv1.EnsureGasTopUpResponse, error) {
+	ctx, cancel := c.callContext(ctx)
+	defer cancel()
+	return c.client.EnsureGasTopUp(ctx, req)
+}
+
 func (c *chainGatewayClient) callContext(ctx context.Context) (context.Context, context.CancelFunc) {
 	timeout := c.cfg.CallTimeout
 	if timeout <= 0 {

api/gateway/chain/client/fake.go

@@ -16,6 +16,8 @@ type Fake struct {
 	GetTransferFn         func(ctx context.Context, req *chainv1.GetTransferRequest) (*chainv1.GetTransferResponse, error)
 	ListTransfersFn       func(ctx context.Context, req *chainv1.ListTransfersRequest) (*chainv1.ListTransfersResponse, error)
 	EstimateTransferFeeFn func(ctx context.Context, req *chainv1.EstimateTransferFeeRequest) (*chainv1.EstimateTransferFeeResponse, error)
+	ComputeGasTopUpFn     func(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) (*chainv1.ComputeGasTopUpResponse, error)
+	EnsureGasTopUpFn      func(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) (*chainv1.EnsureGasTopUpResponse, error)
 	CloseFn               func() error
 }
 
@@ -75,6 +77,20 @@ func (f *Fake) EstimateTransferFee(ctx context.Context, req *chainv1.EstimateTra
 	return &chainv1.EstimateTransferFeeResponse{}, nil
 }
 
+func (f *Fake) ComputeGasTopUp(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) (*chainv1.ComputeGasTopUpResponse, error) {
+	if f.ComputeGasTopUpFn != nil {
+		return f.ComputeGasTopUpFn(ctx, req)
+	}
+	return &chainv1.ComputeGasTopUpResponse{}, nil
+}
+
+func (f *Fake) EnsureGasTopUp(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) (*chainv1.EnsureGasTopUpResponse, error) {
+	if f.EnsureGasTopUpFn != nil {
+		return f.EnsureGasTopUpFn(ctx, req)
+	}
+	return &chainv1.EnsureGasTopUpResponse{}, nil
+}
+
 func (f *Fake) Close() error {
 	if f.CloseFn != nil {
 		return f.CloseFn()

api/gateway/chain/config.yml

@@ -38,6 +38,11 @@ chains:
     chain_id: 728126428 # 0x2b6653dc
     native_token: TRX
     rpc_url_env: CHAIN_GATEWAY_RPC_URL
+    gas_topup_policy:
+      buffer_percent: 0.10
+      min_native_balance_trx: 10
+      rounding_unit_trx: 1
+      max_topup_trx: 100
     tokens:
       - symbol: USDT
         contract: "0xa614f803b6fd780986a42c78ec9c7f77e6ded13c"

api/gateway/chain/go.mod

@@ -22,7 +22,7 @@ require (
 
 require (
 	github.com/Microsoft/go-winio v0.6.2 // indirect
-	github.com/ProjectZKM/Ziren/crates/go-runtime/zkvm_runtime v0.0.0-20251223223124-03e3cef63e04 // indirect
+	github.com/ProjectZKM/Ziren/crates/go-runtime/zkvm_runtime v0.0.0-20251225023818-8886bb81c549 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bits-and-blooms/bitset v1.24.4 // indirect
 	github.com/bmatcuk/doublestar/v4 v4.9.1 // indirect

api/gateway/chain/go.sum

@@ -6,8 +6,8 @@ github.com/DataDog/zstd v1.4.5 h1:EndNeuB0l9syBZhut0wns3gV1hL8zX8LIu6ZiVHWLIQ=
 github.com/DataDog/zstd v1.4.5/go.mod h1:1jcaCB/ufaK+sKp1NBhlGmpz41jOoPQ35bpF36t7BBo=
 github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
 github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
-github.com/ProjectZKM/Ziren/crates/go-runtime/zkvm_runtime v0.0.0-20251223223124-03e3cef63e04 h1:wCr/SrKzMrtW9wG85ApPfncRr7ajzkRevhsWnCkl2sE=
-github.com/ProjectZKM/Ziren/crates/go-runtime/zkvm_runtime v0.0.0-20251223223124-03e3cef63e04/go.mod h1:ioLG6R+5bUSO1oeGSDxOV3FADARuMoytZCSX6MEMQkI=
+github.com/ProjectZKM/Ziren/crates/go-runtime/zkvm_runtime v0.0.0-20251225023818-8886bb81c549 h1:NERDcANvDCnspxdMEMLXOMnuITWIWrTQvvhEA8ewBBM=
+github.com/ProjectZKM/Ziren/crates/go-runtime/zkvm_runtime v0.0.0-20251225023818-8886bb81c549/go.mod h1:ioLG6R+5bUSO1oeGSDxOV3FADARuMoytZCSX6MEMQkI=
 github.com/VictoriaMetrics/fastcache v1.13.0 h1:AW4mheMR5Vd9FkAPUv+NH6Nhw+fmbTMGMsNAoA/+4G0=
 github.com/VictoriaMetrics/fastcache v1.13.0/go.mod h1:hHXhl4DA2fTL2HTZDJFXWgW0LNjo6B+4aj2Wmng3TjU=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=

api/gateway/chain/internal/server/internal/serverimp.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"github.com/mitchellh/mapstructure"
+	"github.com/shopspring/decimal"
 	"github.com/tech/sendico/gateway/chain/internal/keymanager"
 	vaultmanager "github.com/tech/sendico/gateway/chain/internal/keymanager/vault"
 	gatewayservice "github.com/tech/sendico/gateway/chain/internal/service/gateway"
@@ -46,11 +47,12 @@ type config struct {
 }
 
 type chainConfig struct {
-	Name        string        `yaml:"name"`
-	RPCURLEnv   string        `yaml:"rpc_url_env"`
-	ChainID     uint64        `yaml:"chain_id"`
-	NativeToken string        `yaml:"native_token"`
-	Tokens      []tokenConfig `yaml:"tokens"`
+	Name           string                `yaml:"name"`
+	RPCURLEnv      string                `yaml:"rpc_url_env"`
+	ChainID        uint64                `yaml:"chain_id"`
+	NativeToken    string                `yaml:"native_token"`
+	Tokens         []tokenConfig         `yaml:"tokens"`
+	GasTopUpPolicy *gasTopUpPolicyConfig `yaml:"gas_topup_policy"`
 }
 
 type serviceWalletConfig struct {
@@ -66,6 +68,19 @@ type tokenConfig struct {
 	ContractEnv string `yaml:"contract_env"`
 }
 
+type gasTopUpPolicyConfig struct {
+	gasTopUpRuleConfig `yaml:",inline"`
+	Native             *gasTopUpRuleConfig `yaml:"native"`
+	Contract           *gasTopUpRuleConfig `yaml:"contract"`
+}
+
+type gasTopUpRuleConfig struct {
+	BufferPercent       float64 `yaml:"buffer_percent"`
+	MinNativeBalanceTRX float64 `yaml:"min_native_balance_trx"`
+	RoundingUnitTRX     float64 `yaml:"rounding_unit_trx"`
+	MaxTopUpTRX         float64 `yaml:"max_topup_trx"`
+}
+
 // Create initialises the chain gateway server implementation.
 func Create(logger mlogger.Logger, file string, debug bool) (*Imp, error) {
 	return &Imp{
@@ -217,17 +232,86 @@ func resolveNetworkConfigs(logger mlogger.Logger, chains []chainConfig) ([]gatew
 			})
 		}
 
+		gasPolicy, err := buildGasTopUpPolicy(chain.Name, chain.GasTopUpPolicy)
+		if err != nil {
+			logger.Error("invalid gas top-up policy", zap.String("chain", chain.Name), zap.Error(err))
+			return nil, err
+		}
+
 		result = append(result, gatewayshared.Network{
-			Name:         chain.Name,
-			RPCURL:       rpcURL,
-			ChainID:      chain.ChainID,
-			NativeToken:  chain.NativeToken,
-			TokenConfigs: contracts,
+			Name:           chain.Name,
+			RPCURL:         rpcURL,
+			ChainID:        chain.ChainID,
+			NativeToken:    chain.NativeToken,
+			TokenConfigs:   contracts,
+			GasTopUpPolicy: gasPolicy,
 		})
 	}
 	return result, nil
 }
 
+func buildGasTopUpPolicy(chainName string, cfg *gasTopUpPolicyConfig) (*gatewayshared.GasTopUpPolicy, error) {
+	if cfg == nil {
+		return nil, nil
+	}
+	defaultRule, defaultSet, err := parseGasTopUpRule(chainName, "default", cfg.gasTopUpRuleConfig)
+	if err != nil {
+		return nil, err
+	}
+	if !defaultSet {
+		return nil, merrors.InvalidArgument(fmt.Sprintf("chain %s gas_topup_policy is required", chainName))
+	}
+
+	policy := &gatewayshared.GasTopUpPolicy{
+		Default: defaultRule,
+	}
+
+	if cfg.Native != nil {
+		rule, set, err := parseGasTopUpRule(chainName, "native", *cfg.Native)
+		if err != nil {
+			return nil, err
+		}
+		if set {
+			policy.Native = &rule
+		}
+	}
+	if cfg.Contract != nil {
+		rule, set, err := parseGasTopUpRule(chainName, "contract", *cfg.Contract)
+		if err != nil {
+			return nil, err
+		}
+		if set {
+			policy.Contract = &rule
+		}
+	}
+
+	return policy, nil
+}
+
+func parseGasTopUpRule(chainName, label string, cfg gasTopUpRuleConfig) (gatewayshared.GasTopUpRule, bool, error) {
+	if cfg.BufferPercent == 0 && cfg.MinNativeBalanceTRX == 0 && cfg.RoundingUnitTRX == 0 && cfg.MaxTopUpTRX == 0 {
+		return gatewayshared.GasTopUpRule{}, false, nil
+	}
+	if cfg.BufferPercent < 0 {
+		return gatewayshared.GasTopUpRule{}, true, merrors.InvalidArgument(fmt.Sprintf("chain %s gas_topup_policy %s buffer_percent must be >= 0", chainName, label))
+	}
+	if cfg.MinNativeBalanceTRX < 0 {
+		return gatewayshared.GasTopUpRule{}, true, merrors.InvalidArgument(fmt.Sprintf("chain %s gas_topup_policy %s min_native_balance_trx must be >= 0", chainName, label))
+	}
+	if cfg.RoundingUnitTRX <= 0 {
+		return gatewayshared.GasTopUpRule{}, true, merrors.InvalidArgument(fmt.Sprintf("chain %s gas_topup_policy %s rounding_unit_trx must be > 0", chainName, label))
+	}
+	if cfg.MaxTopUpTRX <= 0 {
+		return gatewayshared.GasTopUpRule{}, true, merrors.InvalidArgument(fmt.Sprintf("chain %s gas_topup_policy %s max_topup_trx must be > 0", chainName, label))
+	}
+	return gatewayshared.GasTopUpRule{
+		BufferPercent:    decimal.NewFromFloat(cfg.BufferPercent),
+		MinNativeBalance: decimal.NewFromFloat(cfg.MinNativeBalanceTRX),
+		RoundingUnit:     decimal.NewFromFloat(cfg.RoundingUnitTRX),
+		MaxTopUp:         decimal.NewFromFloat(cfg.MaxTopUpTRX),
+	}, true, nil
+}
+
 func resolveServiceWallet(logger mlogger.Logger, cfg serviceWalletConfig) gatewayshared.ServiceWallet {
 	address := strings.TrimSpace(cfg.Address)
 	if address == "" && cfg.AddressEnv != "" {

api/gateway/chain/internal/service/gateway/commands/registry.go

@@ -23,6 +23,8 @@ type Registry struct {
 	GetTransfer      Unary[chainv1.GetTransferRequest, chainv1.GetTransferResponse]
 	ListTransfers    Unary[chainv1.ListTransfersRequest, chainv1.ListTransfersResponse]
 	EstimateTransfer Unary[chainv1.EstimateTransferFeeRequest, chainv1.EstimateTransferFeeResponse]
+	ComputeGasTopUp  Unary[chainv1.ComputeGasTopUpRequest, chainv1.ComputeGasTopUpResponse]
+	EnsureGasTopUp   Unary[chainv1.EnsureGasTopUpRequest, chainv1.EnsureGasTopUpResponse]
 }
 
 type RegistryDeps struct {
@@ -40,5 +42,7 @@ func NewRegistry(deps RegistryDeps) Registry {
 		GetTransfer:         transfer.NewGetTransfer(deps.Transfer.WithLogger("transfer.get")),
 		ListTransfers:       transfer.NewListTransfers(deps.Transfer.WithLogger("transfer.list")),
 		EstimateTransfer:    transfer.NewEstimateTransfer(deps.Transfer.WithLogger("transfer.estimate_fee")),
+		ComputeGasTopUp:     transfer.NewComputeGasTopUp(deps.Transfer.WithLogger("gas_topup.compute")),
+		EnsureGasTopUp:      transfer.NewEnsureGasTopUp(deps.Transfer.WithLogger("gas_topup.ensure")),
 	}
 }

api/gateway/chain/internal/service/gateway/commands/transfer/destination.go

@@ -17,21 +17,21 @@ func resolveDestination(ctx context.Context, deps Deps, dest *chainv1.TransferDe
 	managedRef := strings.TrimSpace(dest.GetManagedWalletRef())
 	external := strings.TrimSpace(dest.GetExternalAddress())
 	if managedRef != "" && external != "" {
-		deps.Logger.Warn("both managed and external destination provided")
+		deps.Logger.Warn("Both managed and external destination provided")
 		return model.TransferDestination{}, merrors.InvalidArgument("destination must be managed_wallet_ref or external_address")
 	}
 	if managedRef != "" {
 		wallet, err := deps.Storage.Wallets().Get(ctx, managedRef)
 		if err != nil {
-			deps.Logger.Warn("destination wallet lookup failed", zap.Error(err), zap.String("managed_wallet_ref", managedRef))
+			deps.Logger.Warn("Destination wallet lookup failed", zap.Error(err), zap.String("managed_wallet_ref", managedRef))
 			return model.TransferDestination{}, err
 		}
 		if !strings.EqualFold(wallet.Network, source.Network) {
-			deps.Logger.Warn("destination wallet network mismatch", zap.String("source_network", source.Network), zap.String("dest_network", wallet.Network))
+			deps.Logger.Warn("Destination wallet network mismatch", zap.String("source_network", source.Network), zap.String("dest_network", wallet.Network))
 			return model.TransferDestination{}, merrors.InvalidArgument("destination wallet network mismatch")
 		}
 		if strings.TrimSpace(wallet.DepositAddress) == "" {
-			deps.Logger.Warn("destination wallet missing deposit address", zap.String("managed_wallet_ref", managedRef))
+			deps.Logger.Warn("Destination wallet missing deposit address", zap.String("managed_wallet_ref", managedRef))
 			return model.TransferDestination{}, merrors.InvalidArgument("destination wallet missing deposit address")
 		}
 		return model.TransferDestination{
@@ -40,21 +40,21 @@ func resolveDestination(ctx context.Context, deps Deps, dest *chainv1.TransferDe
 		}, nil
 	}
 	if external == "" {
-		deps.Logger.Warn("destination external address missing")
+		deps.Logger.Warn("Destination external address missing")
 		return model.TransferDestination{}, merrors.InvalidArgument("destination is required")
 	}
 	if deps.Drivers == nil {
-		deps.Logger.Warn("chain drivers missing", zap.String("network", source.Network))
+		deps.Logger.Warn("Chain drivers missing", zap.String("network", source.Network))
 		return model.TransferDestination{}, merrors.Internal("chain drivers not configured")
 	}
 	chainDriver, err := deps.Drivers.Driver(source.Network)
 	if err != nil {
-		deps.Logger.Warn("unsupported chain driver", zap.String("network", source.Network), zap.Error(err))
+		deps.Logger.Warn("Unsupported chain driver", zap.String("network", source.Network), zap.Error(err))
 		return model.TransferDestination{}, merrors.InvalidArgument("unsupported chain for wallet")
 	}
 	normalized, err := chainDriver.NormalizeAddress(external)
 	if err != nil {
-		deps.Logger.Warn("invalid external address", zap.Error(err))
+		deps.Logger.Warn("Invalid external address", zap.Error(err))
 		return model.TransferDestination{}, err
 	}
 	return model.TransferDestination{

api/gateway/chain/internal/service/gateway/commands/transfer/fee.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/tech/sendico/gateway/chain/internal/service/gateway/driver"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mservice"
@@ -23,11 +24,11 @@ func NewEstimateTransfer(deps Deps) *estimateTransferFeeCommand {
 
 func (c *estimateTransferFeeCommand) Execute(ctx context.Context, req *chainv1.EstimateTransferFeeRequest) gsresponse.Responder[chainv1.EstimateTransferFeeResponse] {
 	if err := c.deps.EnsureRepository(ctx); err != nil {
-		c.deps.Logger.Warn("repository unavailable", zap.Error(err))
+		c.deps.Logger.Warn("Repository unavailable", zap.Error(err))
 		return gsresponse.Unavailable[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 	if req == nil {
-		c.deps.Logger.Warn("nil request")
+		c.deps.Logger.Warn("Empty request received")
 		return gsresponse.InvalidArgument[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("request is required"))
 	}
 
@@ -45,59 +46,72 @@ func (c *estimateTransferFeeCommand) Execute(ctx context.Context, req *chainv1.E
 	sourceWallet, err := c.deps.Storage.Wallets().Get(ctx, sourceWalletRef)
 	if err != nil {
 		if errors.Is(err, merrors.ErrNoData) {
-			c.deps.Logger.Warn("source wallet not found", zap.String("source_wallet_ref", sourceWalletRef))
+			c.deps.Logger.Warn("Source wallet not found", zap.String("source_wallet_ref", sourceWalletRef))
 			return gsresponse.NotFound[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 		}
-		c.deps.Logger.Warn("storage get wallet failed", zap.Error(err), zap.String("source_wallet_ref", sourceWalletRef))
+		c.deps.Logger.Warn("Storage get wallet failed", zap.Error(err), zap.String("source_wallet_ref", sourceWalletRef))
 		return gsresponse.Auto[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 
 	networkKey := strings.ToLower(strings.TrimSpace(sourceWallet.Network))
 	networkCfg, ok := c.deps.Networks.Network(networkKey)
 	if !ok {
-		c.deps.Logger.Warn("unsupported chain", zap.String("network", networkKey))
+		c.deps.Logger.Warn("Unsupported chain", zap.String("network", networkKey))
 		return gsresponse.InvalidArgument[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("unsupported chain for wallet"))
 	}
 	if c.deps.Drivers == nil {
-		c.deps.Logger.Warn("chain drivers missing", zap.String("network", networkKey))
+		c.deps.Logger.Warn("Chain drivers missing", zap.String("network", networkKey))
 		return gsresponse.Internal[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, merrors.Internal("chain drivers not configured"))
 	}
 	chainDriver, err := c.deps.Drivers.Driver(networkKey)
 	if err != nil {
-		c.deps.Logger.Warn("unsupported chain driver", zap.String("network", networkKey), zap.Error(err))
+		c.deps.Logger.Warn("Unsupported chain driver", zap.String("network", networkKey), zap.Error(err))
 		return gsresponse.InvalidArgument[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("unsupported chain for wallet"))
 	}
 
 	dest, err := resolveDestination(ctx, c.deps, req.GetDestination(), sourceWallet)
 	if err != nil {
 		if errors.Is(err, merrors.ErrNoData) {
-			c.deps.Logger.Warn("destination not found", zap.String("destination_wallet_ref", req.GetDestination().GetManagedWalletRef()))
+			c.deps.Logger.Warn("Destination not found", zap.String("destination_wallet_ref", req.GetDestination().GetManagedWalletRef()))
 			return gsresponse.NotFound[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 		}
-		c.deps.Logger.Warn("invalid destination", zap.Error(err))
+		c.deps.Logger.Warn("Invalid destination", zap.Error(err))
 		return gsresponse.InvalidArgument[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 
 	destinationAddress, err := destinationAddress(ctx, c.deps, chainDriver, dest)
 	if err != nil {
-		c.deps.Logger.Warn("failed to resolve destination address", zap.Error(err))
+		c.deps.Logger.Warn("Failed to resolve destination address", zap.Error(err))
 		return gsresponse.InvalidArgument[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 
+	walletForFee := sourceWallet
+	nativeCurrency := shared.NativeCurrency(networkCfg)
+	if nativeCurrency != "" && strings.EqualFold(nativeCurrency, amount.GetCurrency()) {
+		copyWallet := *sourceWallet
+		copyWallet.ContractAddress = ""
+		copyWallet.TokenSymbol = nativeCurrency
+		walletForFee = &copyWallet
+	}
+
 	driverDeps := driver.Deps{
 		Logger:     c.deps.Logger,
 		Registry:   c.deps.Networks,
 		RPCTimeout: c.deps.RPCTimeout,
 	}
-	feeMoney, err := chainDriver.EstimateFee(ctx, driverDeps, networkCfg, sourceWallet, destinationAddress, amount)
+	feeMoney, err := chainDriver.EstimateFee(ctx, driverDeps, networkCfg, walletForFee, destinationAddress, amount)
 	if err != nil {
-		c.deps.Logger.Warn("fee estimation failed", zap.Error(err))
+		c.deps.Logger.Warn("Fee estimation failed", zap.Error(err))
 		return gsresponse.Auto[chainv1.EstimateTransferFeeResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 
+	contextLabel := "erc20_transfer"
+	if strings.TrimSpace(walletForFee.ContractAddress) == "" {
+		contextLabel = "native_transfer"
+	}
 	resp := &chainv1.EstimateTransferFeeResponse{
 		NetworkFee:        feeMoney,
-		EstimationContext: "erc20_transfer",
+		EstimationContext: contextLabel,
 	}
 	return gsresponse.Success(resp)
 }

api/gateway/chain/internal/service/gateway/commands/transfer/gas_topup.go

@@ -0,0 +1,290 @@
+package transfer
+
+import (
+	"context"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/commands/wallet"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/driver/evm"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/driver/tron"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
+	"github.com/tech/sendico/gateway/chain/storage/model"
+	"github.com/tech/sendico/pkg/api/routers/gsresponse"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/mservice"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	"go.uber.org/zap"
+)
+
+type computeGasTopUpCommand struct {
+	deps Deps
+}
+
+func NewComputeGasTopUp(deps Deps) *computeGasTopUpCommand {
+	return &computeGasTopUpCommand{deps: deps}
+}
+
+func (c *computeGasTopUpCommand) Execute(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) gsresponse.Responder[chainv1.ComputeGasTopUpResponse] {
+	if err := c.deps.EnsureRepository(ctx); err != nil {
+		c.deps.Logger.Warn("repository unavailable", zap.Error(err))
+		return gsresponse.Unavailable[chainv1.ComputeGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, err)
+	}
+	if req == nil {
+		c.deps.Logger.Warn("nil request")
+		return gsresponse.InvalidArgument[chainv1.ComputeGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("request is required"))
+	}
+
+	walletRef := strings.TrimSpace(req.GetWalletRef())
+	if walletRef == "" {
+		c.deps.Logger.Warn("wallet ref missing")
+		return gsresponse.InvalidArgument[chainv1.ComputeGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("wallet_ref is required"))
+	}
+	estimatedFee := req.GetEstimatedTotalFee()
+	if estimatedFee == nil || strings.TrimSpace(estimatedFee.GetAmount()) == "" || strings.TrimSpace(estimatedFee.GetCurrency()) == "" {
+		c.deps.Logger.Warn("estimated fee missing")
+		return gsresponse.InvalidArgument[chainv1.ComputeGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("estimated_total_fee is required"))
+	}
+
+	topUp, capHit, decision, nativeBalance, walletModel, err := computeGasTopUp(ctx, c.deps, walletRef, estimatedFee)
+	if err != nil {
+		return gsresponse.Auto[chainv1.ComputeGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, err)
+	}
+
+	logDecision(c.deps.Logger, walletRef, estimatedFee, nativeBalance, topUp, capHit, decision, walletModel)
+
+	return gsresponse.Success(&chainv1.ComputeGasTopUpResponse{
+		TopupAmount: topUp,
+		CapHit:      capHit,
+	})
+}
+
+type ensureGasTopUpCommand struct {
+	deps Deps
+}
+
+func NewEnsureGasTopUp(deps Deps) *ensureGasTopUpCommand {
+	return &ensureGasTopUpCommand{deps: deps}
+}
+
+func (c *ensureGasTopUpCommand) Execute(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) gsresponse.Responder[chainv1.EnsureGasTopUpResponse] {
+	if err := c.deps.EnsureRepository(ctx); err != nil {
+		c.deps.Logger.Warn("repository unavailable", zap.Error(err))
+		return gsresponse.Unavailable[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, err)
+	}
+	if req == nil {
+		c.deps.Logger.Warn("nil request")
+		return gsresponse.InvalidArgument[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("request is required"))
+	}
+
+	idempotencyKey := strings.TrimSpace(req.GetIdempotencyKey())
+	if idempotencyKey == "" {
+		c.deps.Logger.Warn("idempotency key missing")
+		return gsresponse.InvalidArgument[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("idempotency_key is required"))
+	}
+	organizationRef := strings.TrimSpace(req.GetOrganizationRef())
+	if organizationRef == "" {
+		c.deps.Logger.Warn("organization ref missing")
+		return gsresponse.InvalidArgument[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("organization_ref is required"))
+	}
+	sourceWalletRef := strings.TrimSpace(req.GetSourceWalletRef())
+	if sourceWalletRef == "" {
+		c.deps.Logger.Warn("source wallet ref missing")
+		return gsresponse.InvalidArgument[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("source_wallet_ref is required"))
+	}
+	targetWalletRef := strings.TrimSpace(req.GetTargetWalletRef())
+	if targetWalletRef == "" {
+		c.deps.Logger.Warn("target wallet ref missing")
+		return gsresponse.InvalidArgument[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("target_wallet_ref is required"))
+	}
+	estimatedFee := req.GetEstimatedTotalFee()
+	if estimatedFee == nil || strings.TrimSpace(estimatedFee.GetAmount()) == "" || strings.TrimSpace(estimatedFee.GetCurrency()) == "" {
+		c.deps.Logger.Warn("estimated fee missing")
+		return gsresponse.InvalidArgument[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("estimated_total_fee is required"))
+	}
+
+	topUp, capHit, decision, nativeBalance, walletModel, err := computeGasTopUp(ctx, c.deps, targetWalletRef, estimatedFee)
+	if err != nil {
+		return gsresponse.Auto[chainv1.EnsureGasTopUpResponse](c.deps.Logger, mservice.ChainGateway, err)
+	}
+
+	logDecision(c.deps.Logger, targetWalletRef, estimatedFee, nativeBalance, topUp, capHit, decision, walletModel)
+
+	if topUp == nil || strings.TrimSpace(topUp.GetAmount()) == "" {
+		return gsresponse.Success(&chainv1.EnsureGasTopUpResponse{
+			TopupAmount: nil,
+			CapHit:      capHit,
+		})
+	}
+
+	submitReq := &chainv1.SubmitTransferRequest{
+		IdempotencyKey:  idempotencyKey,
+		OrganizationRef: organizationRef,
+		SourceWalletRef: sourceWalletRef,
+		Destination: &chainv1.TransferDestination{
+			Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: targetWalletRef},
+		},
+		Amount:          topUp,
+		Metadata:        shared.CloneMetadata(req.GetMetadata()),
+		ClientReference: strings.TrimSpace(req.GetClientReference()),
+	}
+
+	submitResponder := NewSubmitTransfer(c.deps.WithLogger("transfer.submit")).Execute(ctx, submitReq)
+	return func(ctx context.Context) (*chainv1.EnsureGasTopUpResponse, error) {
+		submitResp, err := submitResponder(ctx)
+		if err != nil {
+			return nil, err
+		}
+		return &chainv1.EnsureGasTopUpResponse{
+			TopupAmount: topUp,
+			CapHit:      capHit,
+			Transfer:    submitResp.GetTransfer(),
+		}, nil
+	}
+}
+
+func computeGasTopUp(ctx context.Context, deps Deps, walletRef string, estimatedFee *moneyv1.Money) (*moneyv1.Money, bool, *tron.GasTopUpDecision, *moneyv1.Money, *model.ManagedWallet, error) {
+	walletRef = strings.TrimSpace(walletRef)
+	estimatedFee = shared.CloneMoney(estimatedFee)
+	walletModel, err := deps.Storage.Wallets().Get(ctx, walletRef)
+	if err != nil {
+		return nil, false, nil, nil, nil, err
+	}
+
+	networkKey := strings.ToLower(strings.TrimSpace(walletModel.Network))
+	networkCfg, ok := deps.Networks.Network(networkKey)
+	if !ok {
+		return nil, false, nil, nil, nil, merrors.InvalidArgument("unsupported chain for wallet")
+	}
+
+	nativeBalance, err := nativeBalanceForWallet(ctx, deps, walletModel)
+	if err != nil {
+		return nil, false, nil, nil, nil, err
+	}
+
+	if strings.HasPrefix(networkKey, "tron") {
+		topUp, decision, err := tron.ComputeGasTopUp(networkCfg, walletModel, estimatedFee, nativeBalance)
+		if err != nil {
+			return nil, false, nil, nil, nil, err
+		}
+		return topUp, decision.CapHit, &decision, nativeBalance, walletModel, nil
+	}
+
+	if networkCfg.GasTopUpPolicy != nil {
+		topUp, capHit, err := evm.ComputeGasTopUp(networkCfg, walletModel, estimatedFee, nativeBalance)
+		if err != nil {
+			return nil, false, nil, nil, nil, err
+		}
+		return topUp, capHit, nil, nativeBalance, walletModel, nil
+	}
+
+	topUp, err := defaultGasTopUp(estimatedFee, nativeBalance)
+	if err != nil {
+		return nil, false, nil, nil, nil, err
+	}
+	return topUp, false, nil, nativeBalance, walletModel, nil
+}
+
+func nativeBalanceForWallet(ctx context.Context, deps Deps, walletModel *model.ManagedWallet) (*moneyv1.Money, error) {
+	if walletModel == nil {
+		return nil, merrors.InvalidArgument("wallet is required")
+	}
+	walletDeps := wallet.Deps{
+		Logger:           deps.Logger.Named("wallet"),
+		Drivers:          deps.Drivers,
+		Networks:         deps.Networks,
+		KeyManager:       nil,
+		Storage:          deps.Storage,
+		Clock:            deps.Clock,
+		BalanceCacheTTL:  0,
+		RPCTimeout:       deps.RPCTimeout,
+		EnsureRepository: deps.EnsureRepository,
+	}
+	_, nativeBalance, err := wallet.OnChainWalletBalances(ctx, walletDeps, walletModel)
+	if err != nil {
+		return nil, err
+	}
+	if nativeBalance == nil || strings.TrimSpace(nativeBalance.GetAmount()) == "" || strings.TrimSpace(nativeBalance.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("native balance is unavailable")
+	}
+	return nativeBalance, nil
+}
+
+func defaultGasTopUp(estimatedFee *moneyv1.Money, currentBalance *moneyv1.Money) (*moneyv1.Money, error) {
+	if estimatedFee == nil || strings.TrimSpace(estimatedFee.GetAmount()) == "" || strings.TrimSpace(estimatedFee.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("estimated fee is required")
+	}
+	if currentBalance == nil || strings.TrimSpace(currentBalance.GetAmount()) == "" || strings.TrimSpace(currentBalance.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("native balance is required")
+	}
+	if !strings.EqualFold(estimatedFee.GetCurrency(), currentBalance.GetCurrency()) {
+		return nil, merrors.InvalidArgument("native balance currency mismatch")
+	}
+
+	estimated, err := decimal.NewFromString(strings.TrimSpace(estimatedFee.GetAmount()))
+	if err != nil {
+		return nil, err
+	}
+	current, err := decimal.NewFromString(strings.TrimSpace(currentBalance.GetAmount()))
+	if err != nil {
+		return nil, err
+	}
+	required := estimated.Sub(current)
+	if !required.IsPositive() {
+		return nil, nil
+	}
+	return &moneyv1.Money{
+		Currency: strings.ToUpper(strings.TrimSpace(estimatedFee.GetCurrency())),
+		Amount:   required.String(),
+	}, nil
+}
+
+func logDecision(logger mlogger.Logger, walletRef string, estimatedFee *moneyv1.Money, nativeBalance *moneyv1.Money, topUp *moneyv1.Money, capHit bool, decision *tron.GasTopUpDecision, walletModel *model.ManagedWallet) {
+	if logger == nil {
+		return
+	}
+	fields := []zap.Field{
+		zap.String("wallet_ref", walletRef),
+		zap.String("estimated_total_fee", amountString(estimatedFee)),
+		zap.String("current_native_balance", amountString(nativeBalance)),
+		zap.String("topup_amount", amountString(topUp)),
+		zap.Bool("cap_hit", capHit),
+	}
+	if walletModel != nil {
+		fields = append(fields, zap.String("network", strings.TrimSpace(walletModel.Network)))
+	}
+	if decision != nil {
+		fields = append(fields,
+			zap.String("estimated_total_fee_trx", decision.EstimatedFeeTRX.String()),
+			zap.String("current_native_balance_trx", decision.CurrentBalanceTRX.String()),
+			zap.String("required_trx", decision.RequiredTRX.String()),
+			zap.String("buffered_required_trx", decision.BufferedRequiredTRX.String()),
+			zap.String("min_balance_topup_trx", decision.MinBalanceTopUpTRX.String()),
+			zap.String("raw_topup_trx", decision.RawTopUpTRX.String()),
+			zap.String("rounded_topup_trx", decision.RoundedTopUpTRX.String()),
+			zap.String("topup_trx", decision.TopUpTRX.String()),
+			zap.String("operation_type", decision.OperationType),
+		)
+	}
+	logger.Info("gas top-up decision", fields...)
+}
+
+func amountString(m *moneyv1.Money) string {
+	if m == nil {
+		return ""
+	}
+	amount := strings.TrimSpace(m.GetAmount())
+	currency := strings.TrimSpace(m.GetCurrency())
+	if amount == "" && currency == "" {
+		return ""
+	}
+	if currency == "" {
+		return amount
+	}
+	if amount == "" {
+		return currency
+	}
+	return amount + " " + currency
+}

api/gateway/chain/internal/service/gateway/commands/transfer/submit.go

@@ -25,7 +25,7 @@ func NewSubmitTransfer(deps Deps) *submitTransferCommand {
 
 func (c *submitTransferCommand) Execute(ctx context.Context, req *chainv1.SubmitTransferRequest) gsresponse.Responder[chainv1.SubmitTransferResponse] {
 	if err := c.deps.EnsureRepository(ctx); err != nil {
-		c.deps.Logger.Warn("repository unavailable", zap.Error(err))
+		c.deps.Logger.Warn("Repository unavailable", zap.Error(err))
 		return gsresponse.Unavailable[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 	if req == nil {
@@ -35,84 +35,92 @@ func (c *submitTransferCommand) Execute(ctx context.Context, req *chainv1.Submit
 
 	idempotencyKey := strings.TrimSpace(req.GetIdempotencyKey())
 	if idempotencyKey == "" {
-		c.deps.Logger.Warn("missing idempotency key")
+		c.deps.Logger.Warn("Missing idempotency key")
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("idempotency_key is required"))
 	}
 	organizationRef := strings.TrimSpace(req.GetOrganizationRef())
 	if organizationRef == "" {
-		c.deps.Logger.Warn("missing organization ref")
+		c.deps.Logger.Warn("mMssing organization ref")
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("organization_ref is required"))
 	}
 	sourceWalletRef := strings.TrimSpace(req.GetSourceWalletRef())
 	if sourceWalletRef == "" {
-		c.deps.Logger.Warn("missing source wallet ref")
+		c.deps.Logger.Warn("Missing source wallet ref")
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("source_wallet_ref is required"))
 	}
 	amount := req.GetAmount()
 	if amount == nil {
-		c.deps.Logger.Warn("missing amount")
+		c.deps.Logger.Warn("Missing amount")
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("amount is required"))
 	}
 	amountCurrency := strings.ToUpper(strings.TrimSpace(amount.GetCurrency()))
 	if amountCurrency == "" {
-		c.deps.Logger.Warn("missing amount currency")
+		c.deps.Logger.Warn("Missing amount currency")
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("amount.currency is required"))
 	}
 	amountValue := strings.TrimSpace(amount.GetAmount())
 	if amountValue == "" {
-		c.deps.Logger.Warn("missing amount value")
+		c.deps.Logger.Warn("Missing amount value")
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("amount.amount is required"))
 	}
 
 	sourceWallet, err := c.deps.Storage.Wallets().Get(ctx, sourceWalletRef)
 	if err != nil {
 		if errors.Is(err, merrors.ErrNoData) {
-			c.deps.Logger.Warn("source wallet not found", zap.String("source_wallet_ref", sourceWalletRef))
+			c.deps.Logger.Warn("Source wallet not found", zap.String("source_wallet_ref", sourceWalletRef))
 			return gsresponse.NotFound[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 		}
-		c.deps.Logger.Warn("storage get wallet failed", zap.Error(err), zap.String("source_wallet_ref", sourceWalletRef))
+		c.deps.Logger.Warn("Storage get wallet failed", zap.Error(err), zap.String("source_wallet_ref", sourceWalletRef))
 		return gsresponse.Auto[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 	if !strings.EqualFold(sourceWallet.OrganizationRef, organizationRef) {
-		c.deps.Logger.Warn("organization mismatch", zap.String("wallet_org", sourceWallet.OrganizationRef), zap.String("req_org", organizationRef))
+		c.deps.Logger.Warn("Organization mismatch", zap.String("wallet_org", sourceWallet.OrganizationRef), zap.String("req_org", organizationRef))
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("organization_ref mismatch with wallet"))
 	}
 	networkKey := strings.ToLower(strings.TrimSpace(sourceWallet.Network))
 	networkCfg, ok := c.deps.Networks.Network(networkKey)
 	if !ok {
-		c.deps.Logger.Warn("unsupported chain", zap.String("network", networkKey))
+		c.deps.Logger.Warn("Unsupported chain", zap.String("network", networkKey))
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("unsupported chain for wallet"))
 	}
 
 	destination, err := resolveDestination(ctx, c.deps, req.GetDestination(), sourceWallet)
 	if err != nil {
 		if errors.Is(err, merrors.ErrNoData) {
-			c.deps.Logger.Warn("destination not found", zap.String("destination_wallet_ref", req.GetDestination().GetManagedWalletRef()))
+			c.deps.Logger.Warn("Destination not found", zap.String("destination_wallet_ref", req.GetDestination().GetManagedWalletRef()))
 			return gsresponse.NotFound[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 		}
-		c.deps.Logger.Warn("invalid destination", zap.Error(err))
+		c.deps.Logger.Warn("Invalid destination", zap.Error(err))
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 
 	fees, feeSum, err := convertFees(req.GetFees(), amountCurrency)
 	if err != nil {
-		c.deps.Logger.Warn("fee conversion failed", zap.Error(err))
+		c.deps.Logger.Warn("Fee conversion failed", zap.Error(err))
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 	amountDec, err := decimal.NewFromString(amountValue)
 	if err != nil {
-		c.deps.Logger.Warn("invalid amount", zap.Error(err))
+		c.deps.Logger.Warn("Invalid amount", zap.Error(err))
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("invalid amount"))
 	}
 	netDec := amountDec.Sub(feeSum)
 	if netDec.IsNegative() {
-		c.deps.Logger.Warn("fees exceed amount", zap.String("amount", amountValue), zap.String("fee_sum", feeSum.String()))
+		c.deps.Logger.Warn("Fees exceed amount", zap.String("amount", amountValue), zap.String("fee_sum", feeSum.String()))
 		return gsresponse.InvalidArgument[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("fees exceed amount"))
 	}
 
 	netAmount := shared.CloneMoney(amount)
 	netAmount.Amount = netDec.String()
 
+	effectiveTokenSymbol := sourceWallet.TokenSymbol
+	effectiveContractAddress := sourceWallet.ContractAddress
+	nativeCurrency := shared.NativeCurrency(networkCfg)
+	if nativeCurrency != "" && strings.EqualFold(nativeCurrency, amountCurrency) {
+		effectiveTokenSymbol = nativeCurrency
+		effectiveContractAddress = ""
+	}
+
 	transfer := &model.Transfer{
 		IdempotencyKey:  idempotencyKey,
 		TransferRef:     shared.GenerateTransferRef(),
@@ -120,8 +128,8 @@ func (c *submitTransferCommand) Execute(ctx context.Context, req *chainv1.Submit
 		SourceWalletRef: sourceWalletRef,
 		Destination:     destination,
 		Network:         sourceWallet.Network,
-		TokenSymbol:     sourceWallet.TokenSymbol,
-		ContractAddress: sourceWallet.ContractAddress,
+		TokenSymbol:     effectiveTokenSymbol,
+		ContractAddress: effectiveContractAddress,
 		RequestedAmount: shared.CloneMoney(amount),
 		NetAmount:       netAmount,
 		Fees:            fees,
@@ -133,10 +141,10 @@ func (c *submitTransferCommand) Execute(ctx context.Context, req *chainv1.Submit
 	saved, err := c.deps.Storage.Transfers().Create(ctx, transfer)
 	if err != nil {
 		if errors.Is(err, merrors.ErrDataConflict) {
-			c.deps.Logger.Debug("transfer already exists", zap.String("transfer_ref", transfer.TransferRef), zap.String("idempotency_key", idempotencyKey))
+			c.deps.Logger.Debug("Transfer already exists", zap.String("transfer_ref", transfer.TransferRef), zap.String("idempotency_key", idempotencyKey))
 			return gsresponse.Success(&chainv1.SubmitTransferResponse{Transfer: toProtoTransfer(saved)})
 		}
-		c.deps.Logger.Warn("storage create failed", zap.Error(err), zap.String("transfer_ref", transfer.TransferRef))
+		c.deps.Logger.Warn("Storage create failed", zap.Error(err), zap.String("transfer_ref", transfer.TransferRef))
 		return gsresponse.Auto[chainv1.SubmitTransferResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 

api/gateway/chain/internal/service/gateway/commands/wallet/balance.go

@@ -51,7 +51,7 @@ func (c *getWalletBalanceCommand) Execute(ctx context.Context, req *chainv1.GetW
 		return gsresponse.Auto[chainv1.GetWalletBalanceResponse](c.deps.Logger, mservice.ChainGateway, err)
 	}
 
-	balance, chainErr := onChainWalletBalance(ctx, c.deps, wallet)
+	tokenBalance, nativeBalance, chainErr := OnChainWalletBalances(ctx, c.deps, wallet)
 	if chainErr != nil {
 		c.deps.Logger.Warn("on-chain balance fetch failed, attempting cached balance", zap.Error(chainErr), zap.String("wallet_ref", walletRef))
 		stored, err := c.deps.Storage.Wallets().GetBalance(ctx, walletRef)
@@ -74,37 +74,47 @@ func (c *getWalletBalanceCommand) Execute(ctx context.Context, req *chainv1.GetW
 	}
 
 	calculatedAt := c.now()
-	c.persistCachedBalance(ctx, walletRef, balance, calculatedAt)
+	c.persistCachedBalance(ctx, walletRef, tokenBalance, nativeBalance, calculatedAt)
 
 	return gsresponse.Success(&chainv1.GetWalletBalanceResponse{
-		Balance: onChainBalanceToProto(balance, calculatedAt),
+		Balance: onChainBalanceToProto(tokenBalance, nativeBalance, calculatedAt),
 	})
 }
 
-func onChainBalanceToProto(balance *moneyv1.Money, calculatedAt time.Time) *chainv1.WalletBalance {
-	if balance == nil {
+func onChainBalanceToProto(balance *moneyv1.Money, native *moneyv1.Money, calculatedAt time.Time) *chainv1.WalletBalance {
+	if balance == nil && native == nil {
 		return nil
 	}
-	zero := zeroMoney(balance.Currency)
+	currency := ""
+	if balance != nil {
+		currency = balance.Currency
+	}
+	zero := zeroMoney(currency)
 	return &chainv1.WalletBalance{
 		Available:       balance,
+		NativeAvailable: native,
 		PendingInbound:  zero,
 		PendingOutbound: zero,
 		CalculatedAt:    timestamppb.New(calculatedAt.UTC()),
 	}
 }
 
-func (c *getWalletBalanceCommand) persistCachedBalance(ctx context.Context, walletRef string, available *moneyv1.Money, calculatedAt time.Time) {
-	if available == nil {
+func (c *getWalletBalanceCommand) persistCachedBalance(ctx context.Context, walletRef string, available *moneyv1.Money, nativeAvailable *moneyv1.Money, calculatedAt time.Time) {
+	if available == nil && nativeAvailable == nil {
 		return
 	}
 	record := &model.WalletBalance{
 		WalletRef:       walletRef,
 		Available:       shared.CloneMoney(available),
-		PendingInbound:  zeroMoney(available.Currency),
-		PendingOutbound: zeroMoney(available.Currency),
+		NativeAvailable: shared.CloneMoney(nativeAvailable),
 		CalculatedAt:    calculatedAt,
 	}
+	currency := ""
+	if available != nil {
+		currency = available.Currency
+	}
+	record.PendingInbound = zeroMoney(currency)
+	record.PendingOutbound = zeroMoney(currency)
 	if err := c.deps.Storage.Wallets().SaveBalance(ctx, record); err != nil {
 		c.deps.Logger.Warn("failed to cache wallet balance", zap.String("wallet_ref", walletRef), zap.Error(err))
 	}

api/gateway/chain/internal/service/gateway/commands/wallet/create.go

@@ -82,10 +82,12 @@ func (c *createManagedWalletCommand) Execute(ctx context.Context, req *chainv1.C
 	}
 	contractAddress := strings.ToLower(strings.TrimSpace(asset.GetContractAddress()))
 	if contractAddress == "" {
-		contractAddress = shared.ResolveContractAddress(networkCfg.TokenConfigs, tokenSymbol)
-		if contractAddress == "" {
-			c.deps.Logger.Warn("unsupported token", zap.String("token", tokenSymbol), zap.String("chain", chainKey))
-			return gsresponse.InvalidArgument[chainv1.CreateManagedWalletResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("unsupported token for chain"))
+		if !strings.EqualFold(tokenSymbol, networkCfg.NativeToken) {
+			contractAddress = shared.ResolveContractAddress(networkCfg.TokenConfigs, tokenSymbol)
+			if contractAddress == "" {
+				c.deps.Logger.Warn("unsupported token", zap.String("token", tokenSymbol), zap.String("chain", chainKey))
+				return gsresponse.InvalidArgument[chainv1.CreateManagedWalletResponse](c.deps.Logger, mservice.ChainGateway, merrors.InvalidArgument("unsupported token for chain"))
+			}
 		}
 	}
 

api/gateway/chain/internal/service/gateway/commands/wallet/onchain_balance.go

@@ -12,16 +12,16 @@ import (
 	"go.uber.org/zap"
 )
 
-func onChainWalletBalance(ctx context.Context, deps Deps, wallet *model.ManagedWallet) (*moneyv1.Money, error) {
+func OnChainWalletBalances(ctx context.Context, deps Deps, wallet *model.ManagedWallet) (*moneyv1.Money, *moneyv1.Money, error) {
 	logger := deps.Logger
 	if wallet == nil {
-		return nil, merrors.InvalidArgument("wallet is required")
+		return nil, nil, merrors.InvalidArgument("wallet is required")
 	}
 	if deps.Networks == nil {
-		return nil, merrors.Internal("rpc clients not initialised")
+		return nil, nil, merrors.Internal("rpc clients not initialised")
 	}
 	if deps.Drivers == nil {
-		return nil, merrors.Internal("chain drivers not configured")
+		return nil, nil, merrors.Internal("chain drivers not configured")
 	}
 
 	networkKey := strings.ToLower(strings.TrimSpace(wallet.Network))
@@ -31,7 +31,7 @@ func onChainWalletBalance(ctx context.Context, deps Deps, wallet *model.ManagedW
 			zap.String("wallet_ref", wallet.WalletRef),
 			zap.String("network", networkKey),
 		)
-		return nil, merrors.Internal(fmt.Sprintf("Requested network '%s' is not configured", networkKey))
+		return nil, nil, merrors.Internal(fmt.Sprintf("Requested network '%s' is not configured", networkKey))
 	}
 
 	chainDriver, err := deps.Drivers.Driver(networkKey)
@@ -41,7 +41,7 @@ func onChainWalletBalance(ctx context.Context, deps Deps, wallet *model.ManagedW
 			zap.String("network", networkKey),
 			zap.Error(err),
 		)
-		return nil, merrors.InvalidArgument("unsupported chain")
+		return nil, nil, merrors.InvalidArgument("unsupported chain")
 	}
 
 	driverDeps := driver.Deps{
@@ -50,5 +50,13 @@ func onChainWalletBalance(ctx context.Context, deps Deps, wallet *model.ManagedW
 		KeyManager: deps.KeyManager,
 		RPCTimeout: deps.RPCTimeout,
 	}
-	return chainDriver.Balance(ctx, driverDeps, network, wallet)
+	tokenBalance, err := chainDriver.Balance(ctx, driverDeps, network, wallet)
+	if err != nil {
+		return nil, nil, err
+	}
+	nativeBalance, err := chainDriver.NativeBalance(ctx, driverDeps, network, wallet)
+	if err != nil {
+		return nil, nil, err
+	}
+	return tokenBalance, nativeBalance, nil
 }

api/gateway/chain/internal/service/gateway/commands/wallet/proto.go

@@ -58,6 +58,7 @@ func toProtoWalletBalance(balance *model.WalletBalance) *chainv1.WalletBalance {
 	}
 	return &chainv1.WalletBalance{
 		Available:       shared.CloneMoney(balance.Available),
+		NativeAvailable: shared.CloneMoney(balance.NativeAvailable),
 		PendingInbound:  shared.CloneMoney(balance.PendingInbound),
 		PendingOutbound: shared.CloneMoney(balance.PendingOutbound),
 		CalculatedAt:    timestamppb.New(balance.CalculatedAt.UTC()),

api/gateway/chain/internal/service/gateway/driver/arbitrum/driver.go

@@ -69,8 +69,33 @@ func (d *Driver) Balance(ctx context.Context, deps driver.Deps, network shared.N
 	return result, err
 }
 
+func (d *Driver) NativeBalance(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet) (*moneyv1.Money, error) {
+	d.logger.Debug("native balance request",
+		zap.String("wallet_ref", wallet.WalletRef),
+		zap.String("network", network.Name),
+	)
+	driverDeps := deps
+	driverDeps.Logger = d.logger
+	result, err := evm.NativeBalance(ctx, driverDeps, network, wallet, wallet.DepositAddress)
+	if err != nil {
+		d.logger.Warn("native balance failed",
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("network", network.Name),
+			zap.Error(err),
+		)
+	} else if result != nil {
+		d.logger.Debug("native balance result",
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("network", network.Name),
+			zap.String("amount", result.Amount),
+			zap.String("currency", result.Currency),
+		)
+	}
+	return result, err
+}
+
 func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet, destination string, amount *moneyv1.Money) (*moneyv1.Money, error) {
-	d.logger.Debug("estimate fee request",
+	d.logger.Debug("Estimate fee request",
 		zap.String("wallet_ref", wallet.WalletRef),
 		zap.String("network", network.Name),
 		zap.String("destination", destination),
@@ -79,13 +104,13 @@ func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shar
 	driverDeps.Logger = d.logger
 	result, err := evm.EstimateFee(ctx, driverDeps, network, wallet, wallet.DepositAddress, destination, amount)
 	if err != nil {
-		d.logger.Warn("estimate fee failed",
+		d.logger.Warn("Estimate fee failed",
 			zap.String("wallet_ref", wallet.WalletRef),
 			zap.String("network", network.Name),
 			zap.Error(err),
 		)
 	} else if result != nil {
-		d.logger.Debug("estimate fee result",
+		d.logger.Debug("Estimate fee result",
 			zap.String("wallet_ref", wallet.WalletRef),
 			zap.String("network", network.Name),
 			zap.String("amount", result.Amount),

api/gateway/chain/internal/service/gateway/driver/driver.go

@@ -27,6 +27,7 @@ type Driver interface {
 	FormatAddress(address string) (string, error)
 	NormalizeAddress(address string) (string, error)
 	Balance(ctx context.Context, deps Deps, network shared.Network, wallet *model.ManagedWallet) (*moneyv1.Money, error)
+	NativeBalance(ctx context.Context, deps Deps, network shared.Network, wallet *model.ManagedWallet) (*moneyv1.Money, error)
 	EstimateFee(ctx context.Context, deps Deps, network shared.Network, wallet *model.ManagedWallet, destination string, amount *moneyv1.Money) (*moneyv1.Money, error)
 	SubmitTransfer(ctx context.Context, deps Deps, network shared.Network, transfer *model.Transfer, source *model.ManagedWallet, destination string) (string, error)
 	AwaitConfirmation(ctx context.Context, deps Deps, network shared.Network, txHash string) (*types.Receipt, error)

api/gateway/chain/internal/service/gateway/driver/ethereum/driver.go

@@ -69,8 +69,33 @@ func (d *Driver) Balance(ctx context.Context, deps driver.Deps, network shared.N
 	return result, err
 }
 
+func (d *Driver) NativeBalance(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet) (*moneyv1.Money, error) {
+	d.logger.Debug("native balance request",
+		zap.String("wallet_ref", wallet.WalletRef),
+		zap.String("network", network.Name),
+	)
+	driverDeps := deps
+	driverDeps.Logger = d.logger
+	result, err := evm.NativeBalance(ctx, driverDeps, network, wallet, wallet.DepositAddress)
+	if err != nil {
+		d.logger.Warn("native balance failed",
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("network", network.Name),
+			zap.Error(err),
+		)
+	} else if result != nil {
+		d.logger.Debug("native balance result",
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("network", network.Name),
+			zap.String("amount", result.Amount),
+			zap.String("currency", result.Currency),
+		)
+	}
+	return result, err
+}
+
 func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet, destination string, amount *moneyv1.Money) (*moneyv1.Money, error) {
-	d.logger.Debug("estimate fee request",
+	d.logger.Debug("Estimate fee request",
 		zap.String("wallet_ref", wallet.WalletRef),
 		zap.String("network", network.Name),
 		zap.String("destination", destination),
@@ -79,13 +104,13 @@ func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shar
 	driverDeps.Logger = d.logger
 	result, err := evm.EstimateFee(ctx, driverDeps, network, wallet, wallet.DepositAddress, destination, amount)
 	if err != nil {
-		d.logger.Warn("estimate fee failed",
+		d.logger.Warn("Estimate fee failed",
 			zap.String("wallet_ref", wallet.WalletRef),
 			zap.String("network", network.Name),
 			zap.Error(err),
 		)
 	} else if result != nil {
-		d.logger.Debug("estimate fee result",
+		d.logger.Debug("Estimate fee result",
 			zap.String("wallet_ref", wallet.WalletRef),
 			zap.String("network", network.Name),
 			zap.String("amount", result.Amount),

api/gateway/chain/internal/service/gateway/driver/evm/estimate_gas_test.go

@@ -0,0 +1,31 @@
+package evm
+
+import (
+	"math/big"
+	"strings"
+	"testing"
+
+	"github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/stretchr/testify/require"
+)
+
+func TestTronEstimateCallUsesData(t *testing.T) {
+	from := common.HexToAddress("0xfa89b4d534bdeb2713d4ffd893e79d6535fb58f8")
+	to := common.HexToAddress("0xa614f803b6fd780986a42c78ec9c7f77e6ded13c")
+	callMsg := ethereum.CallMsg{
+		From:     from,
+		To:       &to,
+		GasPrice: big.NewInt(100),
+		Data:     []byte{0xa9, 0x05, 0x9c, 0xbb},
+	}
+
+	call := tronEstimateCall(callMsg)
+
+	require.Equal(t, strings.ToLower(from.Hex()), call["from"])
+	require.Equal(t, strings.ToLower(to.Hex()), call["to"])
+	require.Equal(t, "0x64", call["gasPrice"])
+	require.Equal(t, "0xa9059cbb", call["data"])
+	_, hasInput := call["input"]
+	require.False(t, hasInput)
+}

api/gateway/chain/internal/service/gateway/driver/evm/evm.go

@@ -10,6 +10,7 @@ import (
 	"github.com/ethereum/go-ethereum"
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
 	"github.com/ethereum/go-ethereum/core/types"
 	"github.com/ethereum/go-ethereum/rpc"
 	"github.com/shopspring/decimal"
@@ -70,9 +71,32 @@ func NormalizeAddress(address string) (string, error) {
 	return strings.ToLower(common.HexToAddress(trimmed).Hex()), nil
 }
 
+func nativeCurrency(network shared.Network) string {
+	currency := strings.ToUpper(strings.TrimSpace(network.NativeToken))
+	if currency == "" {
+		currency = strings.ToUpper(network.Name)
+	}
+	return currency
+}
+
+func parseBaseUnitAmount(amount string) (*big.Int, error) {
+	trimmed := strings.TrimSpace(amount)
+	if trimmed == "" {
+		return nil, merrors.InvalidArgument("amount is required")
+	}
+	value, ok := new(big.Int).SetString(trimmed, 10)
+	if !ok {
+		return nil, merrors.InvalidArgument("invalid amount")
+	}
+	if value.Sign() < 0 {
+		return nil, merrors.InvalidArgument("amount must be non-negative")
+	}
+	return value, nil
+}
+
 // Balance fetches ERC20 token balance for the provided address.
 func Balance(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet, address string) (*moneyv1.Money, error) {
-	logger := deps.Logger
+	logger := deps.Logger.Named("evm")
 	registry := deps.Registry
 
 	if registry == nil {
@@ -101,7 +125,11 @@ func Balance(ctx context.Context, deps driver.Deps, network shared.Network, wall
 	}
 
 	contract := strings.TrimSpace(wallet.ContractAddress)
-	if contract == "" || !common.IsHexAddress(contract) {
+	if contract == "" {
+		logger.Debug("Native balance requested", logFields...)
+		return NativeBalance(ctx, deps, network, wallet, normalizedAddress)
+	}
+	if !common.IsHexAddress(contract) {
 		logger.Warn("Invalid contract address for balance fetch", logFields...)
 		return nil, merrors.InvalidArgument("invalid contract address")
 	}
@@ -146,9 +174,67 @@ func Balance(ctx context.Context, deps driver.Deps, network shared.Network, wall
 	return &moneyv1.Money{Currency: wallet.TokenSymbol, Amount: dec.String()}, nil
 }
 
+// NativeBalance fetches native token balance for the provided address.
+func NativeBalance(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet, address string) (*moneyv1.Money, error) {
+	logger := deps.Logger.Named("evm")
+	registry := deps.Registry
+
+	if registry == nil {
+		return nil, merrors.Internal("rpc clients not initialised")
+	}
+	if wallet == nil {
+		return nil, merrors.InvalidArgument("wallet is required")
+	}
+
+	normalizedAddress, err := NormalizeAddress(address)
+	if err != nil {
+		return nil, err
+	}
+
+	rpcURL := strings.TrimSpace(network.RPCURL)
+	logFields := []zap.Field{
+		zap.String("wallet_ref", wallet.WalletRef),
+		zap.String("network", strings.ToLower(strings.TrimSpace(network.Name))),
+		zap.String("wallet_address", normalizedAddress),
+	}
+	if rpcURL == "" {
+		logger.Warn("Network rpc url is not configured", logFields...)
+		return nil, merrors.Internal("network rpc url is not configured")
+	}
+
+	client, err := registry.Client(network.Name)
+	if err != nil {
+		logger.Warn("Failed to fetch rpc client", append(logFields, zap.Error(err))...)
+		return nil, err
+	}
+
+	timeout := deps.RPCTimeout
+	if timeout <= 0 {
+		timeout = 10 * time.Second
+	}
+	timeoutCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	bal, err := client.BalanceAt(timeoutCtx, common.HexToAddress(normalizedAddress), nil)
+	if err != nil {
+		logger.Warn("Native balance call failed", append(logFields, zap.Error(err))...)
+		return nil, err
+	}
+
+	logger.Info("On-chain native balance fetched",
+		append(logFields,
+			zap.String("balance_raw", bal.String()),
+		)...,
+	)
+	return &moneyv1.Money{
+		Currency: nativeCurrency(network),
+		Amount:   bal.String(),
+	}, nil
+}
+
 // EstimateFee estimates ERC20 transfer fees for the given parameters.
 func EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet, fromAddress, destination string, amount *moneyv1.Money) (*moneyv1.Money, error) {
-	logger := deps.Logger
+	logger := deps.Logger.Named("evm")
 	registry := deps.Registry
 
 	if registry == nil {
@@ -165,12 +251,6 @@ func EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network,
 	if rpcURL == "" {
 		return nil, merrors.InvalidArgument("network rpc url not configured")
 	}
-	if strings.TrimSpace(wallet.ContractAddress) == "" {
-		return nil, merrors.NotImplemented("native token transfers not supported")
-	}
-	if !common.IsHexAddress(wallet.ContractAddress) {
-		return nil, merrors.InvalidArgument("invalid token contract address")
-	}
 	if _, err := NormalizeAddress(fromAddress); err != nil {
 		return nil, merrors.InvalidArgument("invalid source wallet address")
 	}
@@ -180,10 +260,12 @@ func EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network,
 
 	client, err := registry.Client(network.Name)
 	if err != nil {
+		logger.Warn("Failed to resolve client", zap.Error(err), zap.String("network_name", network.Name))
 		return nil, err
 	}
 	rpcClient, err := registry.RPCClient(network.Name)
 	if err != nil {
+		logger.Warn("Failed to resolve RPC client", zap.Error(err), zap.String("network_name", network.Name))
 		return nil, err
 	}
 
@@ -194,10 +276,46 @@ func EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network,
 	timeoutCtx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
-	tokenAddr := common.HexToAddress(wallet.ContractAddress)
+	contract := strings.TrimSpace(wallet.ContractAddress)
 	toAddr := common.HexToAddress(destination)
 	fromAddr := common.HexToAddress(fromAddress)
 
+	if contract == "" {
+		amountBase, err := parseBaseUnitAmount(amount.GetAmount())
+		if err != nil {
+			logger.Warn("Failed to parse base unit amount", zap.Error(err), zap.String("amount", amount.GetAmount()))
+			return nil, err
+		}
+		gasPrice, err := client.SuggestGasPrice(timeoutCtx)
+		if err != nil {
+			logger.Warn("Failed to suggest gas price", zap.Error(err))
+			return nil, merrors.Internal("failed to suggest gas price: " + err.Error())
+		}
+		callMsg := ethereum.CallMsg{
+			From:     fromAddr,
+			To:       &toAddr,
+			GasPrice: gasPrice,
+			Value:    amountBase,
+		}
+		gasLimit, err := estimateGas(timeoutCtx, network, client, rpcClient, callMsg)
+		if err != nil {
+			logger.Warn("Failed to estimate gas", zap.Error(err), zap.Any("call_mesasge", callMsg))
+			return nil, merrors.Internal("failed to estimate gas: " + err.Error())
+		}
+		fee := new(big.Int).Mul(gasPrice, new(big.Int).SetUint64(gasLimit))
+		feeDec := decimal.NewFromBigInt(fee, 0)
+		return &moneyv1.Money{
+			Currency: nativeCurrency(network),
+			Amount:   feeDec.String(),
+		}, nil
+	}
+	if !common.IsHexAddress(contract) {
+		logger.Warn("Failed to validate contract", zap.String("contract", contract))
+		return nil, merrors.InvalidArgument("invalid token contract address")
+	}
+
+	tokenAddr := common.HexToAddress(contract)
+
 	decimals, err := erc20Decimals(timeoutCtx, rpcClient, tokenAddr)
 	if err != nil {
 		logger.Warn("Failed to read token decimals", zap.Error(err))
@@ -211,11 +329,13 @@ func EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network,
 
 	input, err := erc20ABI.Pack("transfer", toAddr, amountBase)
 	if err != nil {
+		logger.Warn("Failed to encode transfer call", zap.Error(err))
 		return nil, merrors.Internal("failed to encode transfer call: " + err.Error())
 	}
 
 	gasPrice, err := client.SuggestGasPrice(timeoutCtx)
 	if err != nil {
+		logger.Warn("Failed to suggest gas price", zap.Error(err))
 		return nil, merrors.Internal("failed to suggest gas price: " + err.Error())
 	}
 
@@ -225,28 +345,24 @@ func EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network,
 		GasPrice: gasPrice,
 		Data:     input,
 	}
-	gasLimit, err := client.EstimateGas(timeoutCtx, callMsg)
+	gasLimit, err := estimateGas(timeoutCtx, network, client, rpcClient, callMsg)
 	if err != nil {
+		logger.Warn("Failed to estimate gas", zap.Error(err), zap.Any("call_message", callMsg))
 		return nil, merrors.Internal("failed to estimate gas: " + err.Error())
 	}
 
 	fee := new(big.Int).Mul(gasPrice, new(big.Int).SetUint64(gasLimit))
 	feeDec := decimal.NewFromBigInt(fee, 0)
 
-	currency := strings.ToUpper(strings.TrimSpace(network.NativeToken))
-	if currency == "" {
-		currency = strings.ToUpper(network.Name)
-	}
-
 	return &moneyv1.Money{
-		Currency: currency,
+		Currency: nativeCurrency(network),
 		Amount:   feeDec.String(),
 	}, nil
 }
 
 // SubmitTransfer submits an ERC20 transfer on an EVM-compatible chain.
 func SubmitTransfer(ctx context.Context, deps driver.Deps, network shared.Network, transfer *model.Transfer, source *model.ManagedWallet, fromAddress, destination string) (string, error) {
-	logger := deps.Logger
+	logger := deps.Logger.Named("evm")
 	registry := deps.Registry
 
 	if deps.KeyManager == nil {
@@ -278,7 +394,7 @@ func SubmitTransfer(ctx context.Context, deps driver.Deps, network shared.Networ
 		return "", executorInvalid("invalid destination address " + destination)
 	}
 
-	logger.Info("submitting transfer",
+	logger.Info("Submitting transfer",
 		zap.String("transfer_ref", transfer.TransferRef),
 		zap.String("source_wallet_ref", source.WalletRef),
 		zap.String("network", network.Name),
@@ -287,12 +403,12 @@ func SubmitTransfer(ctx context.Context, deps driver.Deps, network shared.Networ
 
 	client, err := registry.Client(network.Name)
 	if err != nil {
-		logger.Warn("Failed to initialise rpc client", zap.Error(err), zap.String("network", network.Name))
+		logger.Warn("Failed to initialise RPC client", zap.Error(err), zap.String("network", network.Name))
 		return "", err
 	}
 	rpcClient, err := registry.RPCClient(network.Name)
 	if err != nil {
-		logger.Warn("failed to initialise rpc client", zap.String("network", network.Name))
+		logger.Warn("Failed to initialise RPC client", zap.String("network", network.Name))
 		return "", err
 	}
 
@@ -322,66 +438,86 @@ func SubmitTransfer(ctx context.Context, deps driver.Deps, network shared.Networ
 
 	chainID := new(big.Int).SetUint64(network.ChainID)
 
-	if strings.TrimSpace(transfer.ContractAddress) == "" {
-		logger.Warn("Native token transfer requested but not supported", zap.String("transfer_ref", transfer.TransferRef))
-		return "", merrors.NotImplemented("executor: native token transfers not yet supported")
-	}
-
-	if !common.IsHexAddress(transfer.ContractAddress) {
-		logger.Warn("Invalid token contract address",
-			zap.String("transfer_ref", transfer.TransferRef),
-			zap.String("contract", transfer.ContractAddress),
-		)
-		return "", executorInvalid("invalid token contract address " + transfer.ContractAddress)
-	}
-	tokenAddress := common.HexToAddress(transfer.ContractAddress)
-
-	decimals, err := erc20Decimals(ctx, rpcClient, tokenAddress)
-	if err != nil {
-		logger.Warn("Failed to read token decimals", zap.Error(err),
-			zap.String("transfer_ref", transfer.TransferRef),
-			zap.String("contract", transfer.ContractAddress),
-		)
-		return "", err
-	}
-
+	contract := strings.TrimSpace(transfer.ContractAddress)
 	amount := transfer.NetAmount
 	if amount == nil || strings.TrimSpace(amount.Amount) == "" {
 		logger.Warn("Transfer missing net amount", zap.String("transfer_ref", transfer.TransferRef))
 		return "", executorInvalid("transfer missing net amount")
 	}
-	amountInt, err := toBaseUnits(amount.Amount, decimals)
-	if err != nil {
-		logger.Warn("Failed to convert amount to base units", zap.Error(err),
-			zap.String("transfer_ref", transfer.TransferRef),
-			zap.String("amount", amount.Amount),
-		)
-		return "", err
-	}
 
-	input, err := erc20ABI.Pack("transfer", destinationAddr, amountInt)
-	if err != nil {
-		logger.Warn("Failed to encode transfer call", zap.Error(err),
-			zap.String("transfer_ref", transfer.TransferRef),
-		)
-		return "", executorInternal("failed to encode transfer call", err)
-	}
+	var tx *types.Transaction
+	if contract == "" {
+		amountInt, err := parseBaseUnitAmount(amount.Amount)
+		if err != nil {
+			logger.Warn("Invalid native amount", zap.Error(err), zap.String("transfer_ref", transfer.TransferRef))
+			return "", err
+		}
+		callMsg := ethereum.CallMsg{
+			From:     sourceAddress,
+			To:       &destinationAddr,
+			GasPrice: gasPrice,
+			Value:    amountInt,
+		}
+		gasLimit, err := estimateGas(ctx, network, client, rpcClient, callMsg)
+		if err != nil {
+			logger.Warn("Failed to estimate gas", zap.Error(err),
+				zap.String("transfer_ref", transfer.TransferRef),
+			)
+			return "", executorInternal("failed to estimate gas", err)
+		}
+		tx = types.NewTransaction(nonce, destinationAddr, amountInt, gasLimit, gasPrice, nil)
+	} else {
+		if !common.IsHexAddress(contract) {
+			logger.Warn("Invalid token contract address",
+				zap.String("transfer_ref", transfer.TransferRef),
+				zap.String("contract", contract),
+			)
+			return "", executorInvalid("invalid token contract address " + contract)
+		}
+		tokenAddress := common.HexToAddress(contract)
 
-	callMsg := ethereum.CallMsg{
-		From:     sourceAddress,
-		To:       &tokenAddress,
-		GasPrice: gasPrice,
-		Data:     input,
-	}
-	gasLimit, err := client.EstimateGas(ctx, callMsg)
-	if err != nil {
-		logger.Warn("Failed to estimate gas", zap.Error(err),
-			zap.String("transfer_ref", transfer.TransferRef),
-		)
-		return "", executorInternal("failed to estimate gas", err)
-	}
+		decimals, err := erc20Decimals(ctx, rpcClient, tokenAddress)
+		if err != nil {
+			logger.Warn("Failed to read token decimals", zap.Error(err),
+				zap.String("transfer_ref", transfer.TransferRef),
+				zap.String("contract", contract),
+			)
+			return "", err
+		}
 
-	tx := types.NewTransaction(nonce, tokenAddress, big.NewInt(0), gasLimit, gasPrice, input)
+		amountInt, err := toBaseUnits(amount.Amount, decimals)
+		if err != nil {
+			logger.Warn("Failed to convert amount to base units", zap.Error(err),
+				zap.String("transfer_ref", transfer.TransferRef),
+				zap.String("amount", amount.Amount),
+			)
+			return "", err
+		}
+
+		input, err := erc20ABI.Pack("transfer", destinationAddr, amountInt)
+		if err != nil {
+			logger.Warn("Failed to encode transfer call", zap.Error(err),
+				zap.String("transfer_ref", transfer.TransferRef),
+			)
+			return "", executorInternal("failed to encode transfer call", err)
+		}
+
+		callMsg := ethereum.CallMsg{
+			From:     sourceAddress,
+			To:       &tokenAddress,
+			GasPrice: gasPrice,
+			Data:     input,
+		}
+		gasLimit, err := estimateGas(ctx, network, client, rpcClient, callMsg)
+		if err != nil {
+			logger.Warn("Failed to estimate gas", zap.Error(err),
+				zap.String("transfer_ref", transfer.TransferRef),
+			)
+			return "", executorInternal("failed to estimate gas", err)
+		}
+
+		tx = types.NewTransaction(nonce, tokenAddress, big.NewInt(0), gasLimit, gasPrice, input)
+	}
 
 	signedTx, err := deps.KeyManager.SignTransaction(ctx, source.KeyReference, tx, chainID)
 	if err != nil {
@@ -411,7 +547,7 @@ func SubmitTransfer(ctx context.Context, deps driver.Deps, network shared.Networ
 
 // AwaitConfirmation waits for the transaction receipt.
 func AwaitConfirmation(ctx context.Context, deps driver.Deps, network shared.Network, txHash string) (*types.Receipt, error) {
-	logger := deps.Logger
+	logger := deps.Logger.Named("evm")
 	registry := deps.Registry
 
 	if strings.TrimSpace(txHash) == "" {
@@ -526,6 +662,63 @@ func erc20Decimals(ctx context.Context, client *rpc.Client, token common.Address
 	return val, nil
 }
 
+type gasEstimator interface {
+	EstimateGas(ctx context.Context, msg ethereum.CallMsg) (uint64, error)
+}
+
+func estimateGas(ctx context.Context, network shared.Network, client gasEstimator, rpcClient *rpc.Client, callMsg ethereum.CallMsg) (uint64, error) {
+	if isTronNetwork(network) {
+		if rpcClient == nil {
+			return 0, merrors.Internal("rpc client not initialised")
+		}
+		return estimateGasTron(ctx, rpcClient, callMsg)
+	}
+	return client.EstimateGas(ctx, callMsg)
+}
+
+func estimateGasTron(ctx context.Context, rpcClient *rpc.Client, callMsg ethereum.CallMsg) (uint64, error) {
+	call := tronEstimateCall(callMsg)
+	var hexResp string
+	if err := rpcClient.CallContext(ctx, &hexResp, "eth_estimateGas", call); err != nil {
+		return 0, err
+	}
+	val, err := shared.DecodeHexBig(hexResp)
+	if err != nil {
+		return 0, err
+	}
+	if val == nil {
+		return 0, merrors.Internal("failed to decode gas estimate")
+	}
+	return val.Uint64(), nil
+}
+
+func tronEstimateCall(callMsg ethereum.CallMsg) map[string]string {
+	call := make(map[string]string)
+	if callMsg.From != (common.Address{}) {
+		call["from"] = strings.ToLower(callMsg.From.Hex())
+	}
+	if callMsg.To != nil {
+		call["to"] = strings.ToLower(callMsg.To.Hex())
+	}
+	if callMsg.Gas > 0 {
+		call["gas"] = hexutil.EncodeUint64(callMsg.Gas)
+	}
+	if callMsg.GasPrice != nil {
+		call["gasPrice"] = hexutil.EncodeBig(callMsg.GasPrice)
+	}
+	if callMsg.Value != nil {
+		call["value"] = hexutil.EncodeBig(callMsg.Value)
+	}
+	if len(callMsg.Data) > 0 {
+		call["data"] = hexutil.Encode(callMsg.Data)
+	}
+	return call
+}
+
+func isTronNetwork(network shared.Network) bool {
+	return strings.HasPrefix(strings.ToLower(strings.TrimSpace(network.Name)), "tron")
+}
+
 func toBaseUnits(amount string, decimals uint8) (*big.Int, error) {
 	value, err := decimal.NewFromString(strings.TrimSpace(amount))
 	if err != nil {

api/gateway/chain/internal/service/gateway/driver/evm/gas_topup.go

@@ -0,0 +1,108 @@
+package evm
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
+	"github.com/tech/sendico/gateway/chain/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+)
+
+var evmBaseUnitFactor = decimal.NewFromInt(1_000_000_000_000_000_000)
+
+// ComputeGasTopUp applies the network policy to decide an EVM native-token top-up amount.
+func ComputeGasTopUp(network shared.Network, wallet *model.ManagedWallet, estimatedFee *moneyv1.Money, currentBalance *moneyv1.Money) (*moneyv1.Money, bool, error) {
+	if wallet == nil {
+		return nil, false, merrors.InvalidArgument("wallet is required")
+	}
+	if estimatedFee == nil || strings.TrimSpace(estimatedFee.GetAmount()) == "" || strings.TrimSpace(estimatedFee.GetCurrency()) == "" {
+		return nil, false, merrors.InvalidArgument("estimated fee is required")
+	}
+	if currentBalance == nil || strings.TrimSpace(currentBalance.GetAmount()) == "" || strings.TrimSpace(currentBalance.GetCurrency()) == "" {
+		return nil, false, merrors.InvalidArgument("current native balance is required")
+	}
+	if network.GasTopUpPolicy == nil {
+		return nil, false, merrors.InvalidArgument("gas top-up policy is not configured")
+	}
+
+	nativeCurrency := strings.TrimSpace(network.NativeToken)
+	if nativeCurrency == "" {
+		nativeCurrency = strings.ToUpper(strings.TrimSpace(network.Name))
+	}
+	if !strings.EqualFold(nativeCurrency, estimatedFee.GetCurrency()) {
+		return nil, false, merrors.InvalidArgument(fmt.Sprintf("estimated fee currency mismatch (expected %s)", nativeCurrency))
+	}
+	if !strings.EqualFold(nativeCurrency, currentBalance.GetCurrency()) {
+		return nil, false, merrors.InvalidArgument(fmt.Sprintf("native balance currency mismatch (expected %s)", nativeCurrency))
+	}
+
+	estimatedNative, err := evmToNative(estimatedFee)
+	if err != nil {
+		return nil, false, err
+	}
+	currentNative, err := evmToNative(currentBalance)
+	if err != nil {
+		return nil, false, err
+	}
+
+	isContract := strings.TrimSpace(wallet.ContractAddress) != ""
+	rule, ok := network.GasTopUpPolicy.Rule(isContract)
+	if !ok {
+		return nil, false, merrors.InvalidArgument("gas top-up policy is not configured")
+	}
+	if rule.RoundingUnit.LessThanOrEqual(decimal.Zero) {
+		return nil, false, merrors.InvalidArgument("gas top-up rounding unit must be > 0")
+	}
+	if rule.MaxTopUp.LessThanOrEqual(decimal.Zero) {
+		return nil, false, merrors.InvalidArgument("gas top-up max top-up must be > 0")
+	}
+
+	required := estimatedNative.Sub(currentNative)
+	if required.IsNegative() {
+		required = decimal.Zero
+	}
+	bufferedRequired := required.Mul(decimal.NewFromInt(1).Add(rule.BufferPercent))
+
+	minBalanceTopUp := rule.MinNativeBalance.Sub(currentNative)
+	if minBalanceTopUp.IsNegative() {
+		minBalanceTopUp = decimal.Zero
+	}
+
+	rawTopUp := bufferedRequired
+	if minBalanceTopUp.GreaterThan(rawTopUp) {
+		rawTopUp = minBalanceTopUp
+	}
+
+	roundedTopUp := decimal.Zero
+	if rawTopUp.IsPositive() {
+		roundedTopUp = rawTopUp.Div(rule.RoundingUnit).Ceil().Mul(rule.RoundingUnit)
+	}
+
+	topUp := roundedTopUp
+	capHit := false
+	if topUp.GreaterThan(rule.MaxTopUp) {
+		topUp = rule.MaxTopUp
+		capHit = true
+	}
+
+	if !topUp.IsPositive() {
+		return nil, capHit, nil
+	}
+
+	baseUnits := topUp.Mul(evmBaseUnitFactor).Ceil().Truncate(0)
+	return &moneyv1.Money{
+		Currency: strings.ToUpper(nativeCurrency),
+		Amount:   baseUnits.StringFixed(0),
+	}, capHit, nil
+}
+
+func evmToNative(amount *moneyv1.Money) (decimal.Decimal, error) {
+	value, err := decimal.NewFromString(strings.TrimSpace(amount.GetAmount()))
+	if err != nil {
+		return decimal.Zero, err
+	}
+	return value.Div(evmBaseUnitFactor), nil
+}

api/gateway/chain/internal/service/gateway/driver/evm/gas_topup_test.go

@@ -0,0 +1,146 @@
+package evm
+
+import (
+	"testing"
+
+	"github.com/shopspring/decimal"
+	"github.com/stretchr/testify/require"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
+	"github.com/tech/sendico/gateway/chain/storage/model"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+)
+
+func TestComputeGasTopUp_BalanceSufficient(t *testing.T) {
+	network := ethNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("5"), ethMoney("30"))
+	require.NoError(t, err)
+	require.Nil(t, topUp)
+	require.False(t, capHit)
+}
+
+func TestComputeGasTopUp_BufferedRequired(t *testing.T) {
+	network := ethNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("50"), ethMoney("10"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.False(t, capHit)
+	require.Equal(t, "46000000000000000000", topUp.GetAmount())
+	require.Equal(t, "ETH", topUp.GetCurrency())
+}
+
+func TestComputeGasTopUp_MinBalanceBinding(t *testing.T) {
+	network := ethNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("5"), ethMoney("1"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.False(t, capHit)
+	require.Equal(t, "19000000000000000000", topUp.GetAmount())
+}
+
+func TestComputeGasTopUp_RoundsUp(t *testing.T) {
+	policy := shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0),
+			MinNativeBalance: decimal.NewFromFloat(0),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(100),
+		},
+	}
+	network := ethNetwork(&policy)
+	wallet := &model.ManagedWallet{}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("1.1"), ethMoney("0"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.False(t, capHit)
+	require.Equal(t, "2000000000000000000", topUp.GetAmount())
+}
+
+func TestComputeGasTopUp_CapHit(t *testing.T) {
+	policy := shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0),
+			MinNativeBalance: decimal.NewFromFloat(0),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(10),
+		},
+	}
+	network := ethNetwork(&policy)
+	wallet := &model.ManagedWallet{}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("100"), ethMoney("0"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.True(t, capHit)
+	require.Equal(t, "10000000000000000000", topUp.GetAmount())
+}
+
+func TestComputeGasTopUp_MinBalanceWhenRequiredZero(t *testing.T) {
+	network := ethNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("0"), ethMoney("5"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.False(t, capHit)
+	require.Equal(t, "15000000000000000000", topUp.GetAmount())
+}
+
+func TestComputeGasTopUp_ContractPolicyOverride(t *testing.T) {
+	policy := shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0.1),
+			MinNativeBalance: decimal.NewFromFloat(10),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(100),
+		},
+		Contract: &shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0.5),
+			MinNativeBalance: decimal.NewFromFloat(5),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(100),
+		},
+	}
+	network := ethNetwork(&policy)
+	wallet := &model.ManagedWallet{ContractAddress: "0xcontract"}
+
+	topUp, capHit, err := ComputeGasTopUp(network, wallet, ethMoney("10"), ethMoney("0"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.False(t, capHit)
+	require.Equal(t, "15000000000000000000", topUp.GetAmount())
+}
+
+func defaultPolicy() *shared.GasTopUpPolicy {
+	return &shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0.15),
+			MinNativeBalance: decimal.NewFromFloat(20),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(500),
+		},
+	}
+}
+
+func ethNetwork(policy *shared.GasTopUpPolicy) shared.Network {
+	return shared.Network{
+		Name:           "ethereum_mainnet",
+		NativeToken:    "ETH",
+		GasTopUpPolicy: policy,
+	}
+}
+
+func ethMoney(eth string) *moneyv1.Money {
+	value, _ := decimal.NewFromString(eth)
+	baseUnits := value.Mul(evmBaseUnitFactor).Truncate(0)
+	return &moneyv1.Money{
+		Currency: "ETH",
+		Amount:   baseUnits.StringFixed(0),
+	}
+}

api/gateway/chain/internal/service/gateway/driver/tron/driver.go

@@ -2,6 +2,7 @@ package tron
 
 import (
 	"context"
+	"strings"
 
 	"github.com/ethereum/go-ethereum/core/types"
 	"github.com/tech/sendico/gateway/chain/internal/service/gateway/driver"
@@ -77,10 +78,45 @@ func (d *Driver) Balance(ctx context.Context, deps driver.Deps, network shared.N
 	return result, err
 }
 
+func (d *Driver) NativeBalance(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet) (*moneyv1.Money, error) {
+	if wallet == nil {
+		return nil, merrors.InvalidArgument("wallet is required")
+	}
+	d.logger.Debug("Native balance request", zap.String("wallet_ref", wallet.WalletRef), zap.String("network", network.Name))
+	rpcAddr, err := rpcAddress(wallet.DepositAddress)
+	if err != nil {
+		d.logger.Warn("Native balance address conversion failed", zap.Error(err),
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("address", wallet.DepositAddress),
+		)
+		return nil, err
+	}
+	driverDeps := deps
+	driverDeps.Logger = d.logger
+	result, err := evm.NativeBalance(ctx, driverDeps, network, wallet, rpcAddr)
+	if err != nil {
+		d.logger.Warn("Native balance failed", zap.Error(err),
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("network", network.Name),
+		)
+	} else if result != nil {
+		d.logger.Debug("native balance result",
+			zap.String("wallet_ref", wallet.WalletRef),
+			zap.String("network", network.Name),
+			zap.String("amount", result.Amount),
+			zap.String("currency", result.Currency),
+		)
+	}
+	return result, err
+}
+
 func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shared.Network, wallet *model.ManagedWallet, destination string, amount *moneyv1.Money) (*moneyv1.Money, error) {
 	if wallet == nil {
 		return nil, merrors.InvalidArgument("wallet is required")
 	}
+	if amount == nil {
+		return nil, merrors.InvalidArgument("amount is required")
+	}
 	d.logger.Debug("Estimate fee request",
 		zap.String("wallet_ref", wallet.WalletRef),
 		zap.String("network", network.Name),
@@ -102,6 +138,12 @@ func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shar
 		)
 		return nil, err
 	}
+	if rpcFrom == rpcTo {
+		return &moneyv1.Money{
+			Currency: nativeCurrency(network),
+			Amount:   "0",
+		}, nil
+	}
 	driverDeps := deps
 	driverDeps.Logger = d.logger
 	result, err := evm.EstimateFee(ctx, driverDeps, network, wallet, rpcFrom, rpcTo, amount)
@@ -109,6 +151,10 @@ func (d *Driver) EstimateFee(ctx context.Context, deps driver.Deps, network shar
 		d.logger.Warn("Estimate fee failed", zap.Error(err),
 			zap.String("wallet_ref", wallet.WalletRef),
 			zap.String("network", network.Name),
+			zap.String("from_address", wallet.DepositAddress),
+			zap.String("from_rpc", rpcFrom),
+			zap.String("to_address", destination),
+			zap.String("to_rpc", rpcTo),
 		)
 	} else if result != nil {
 		d.logger.Debug("Estimate fee result",
@@ -188,4 +234,12 @@ func (d *Driver) AwaitConfirmation(ctx context.Context, deps driver.Deps, networ
 	return receipt, err
 }
 
+func nativeCurrency(network shared.Network) string {
+	currency := strings.ToUpper(strings.TrimSpace(network.NativeToken))
+	if currency == "" {
+		currency = strings.ToUpper(strings.TrimSpace(network.Name))
+	}
+	return currency
+}
+
 var _ driver.Driver = (*Driver)(nil)

api/gateway/chain/internal/service/gateway/driver/tron/driver_test.go

@@ -0,0 +1,33 @@
+package tron
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/driver"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
+	"github.com/tech/sendico/gateway/chain/storage/model"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	"go.uber.org/zap"
+)
+
+func TestEstimateFeeSelfTransferReturnsZero(t *testing.T) {
+	logger := zap.NewNop()
+	d := New(logger)
+	wallet := &model.ManagedWallet{
+		WalletRef:      "wallet_ref",
+		DepositAddress: "TGBDXEg9rxSqGFJDcb889zqTjDwx1bmLRF",
+	}
+	network := shared.Network{
+		Name:        "tron_mainnet",
+		NativeToken: "TRX",
+	}
+	amount := &moneyv1.Money{Currency: "TRX", Amount: "1000000"}
+
+	fee, err := d.EstimateFee(context.Background(), driver.Deps{}, network, wallet, wallet.DepositAddress, amount)
+	require.NoError(t, err)
+	require.NotNil(t, fee)
+	require.Equal(t, "TRX", fee.GetCurrency())
+	require.Equal(t, "0", fee.GetAmount())
+}

api/gateway/chain/internal/service/gateway/driver/tron/gas_topup.go

@@ -0,0 +1,143 @@
+package tron
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
+	"github.com/tech/sendico/gateway/chain/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+)
+
+var tronBaseUnitFactor = decimal.NewFromInt(1_000_000)
+
+// GasTopUpDecision captures the applied policy inputs and outputs (in TRX units).
+type GasTopUpDecision struct {
+	CurrentBalanceTRX   decimal.Decimal
+	EstimatedFeeTRX     decimal.Decimal
+	RequiredTRX         decimal.Decimal
+	BufferedRequiredTRX decimal.Decimal
+	MinBalanceTopUpTRX  decimal.Decimal
+	RawTopUpTRX         decimal.Decimal
+	RoundedTopUpTRX     decimal.Decimal
+	TopUpTRX            decimal.Decimal
+	CapHit              bool
+	OperationType       string
+}
+
+// ComputeGasTopUp applies the network policy to decide a TRX top-up amount.
+func ComputeGasTopUp(network shared.Network, wallet *model.ManagedWallet, estimatedFee *moneyv1.Money, currentBalance *moneyv1.Money) (*moneyv1.Money, GasTopUpDecision, error) {
+	decision := GasTopUpDecision{}
+	if wallet == nil {
+		return nil, decision, merrors.InvalidArgument("wallet is required")
+	}
+	if estimatedFee == nil || strings.TrimSpace(estimatedFee.GetAmount()) == "" || strings.TrimSpace(estimatedFee.GetCurrency()) == "" {
+		return nil, decision, merrors.InvalidArgument("estimated fee is required")
+	}
+	if currentBalance == nil || strings.TrimSpace(currentBalance.GetAmount()) == "" || strings.TrimSpace(currentBalance.GetCurrency()) == "" {
+		return nil, decision, merrors.InvalidArgument("current native balance is required")
+	}
+	if network.GasTopUpPolicy == nil {
+		return nil, decision, merrors.InvalidArgument("gas top-up policy is not configured")
+	}
+
+	nativeCurrency := strings.TrimSpace(network.NativeToken)
+	if nativeCurrency == "" {
+		nativeCurrency = strings.ToUpper(strings.TrimSpace(network.Name))
+	}
+	if !strings.EqualFold(nativeCurrency, estimatedFee.GetCurrency()) {
+		return nil, decision, merrors.InvalidArgument(fmt.Sprintf("estimated fee currency mismatch (expected %s)", nativeCurrency))
+	}
+	if !strings.EqualFold(nativeCurrency, currentBalance.GetCurrency()) {
+		return nil, decision, merrors.InvalidArgument(fmt.Sprintf("native balance currency mismatch (expected %s)", nativeCurrency))
+	}
+
+	estimatedTRX, err := tronToTRX(estimatedFee)
+	if err != nil {
+		return nil, decision, err
+	}
+	currentTRX, err := tronToTRX(currentBalance)
+	if err != nil {
+		return nil, decision, err
+	}
+
+	isContract := strings.TrimSpace(wallet.ContractAddress) != ""
+	rule, ok := network.GasTopUpPolicy.Rule(isContract)
+	if !ok {
+		return nil, decision, merrors.InvalidArgument("gas top-up policy is not configured")
+	}
+	if rule.RoundingUnit.LessThanOrEqual(decimal.Zero) {
+		return nil, decision, merrors.InvalidArgument("gas top-up rounding unit must be > 0")
+	}
+	if rule.MaxTopUp.LessThanOrEqual(decimal.Zero) {
+		return nil, decision, merrors.InvalidArgument("gas top-up max top-up must be > 0")
+	}
+
+	required := estimatedTRX.Sub(currentTRX)
+	if required.IsNegative() {
+		required = decimal.Zero
+	}
+	bufferedRequired := required.Mul(decimal.NewFromInt(1).Add(rule.BufferPercent))
+
+	minBalanceTopUp := rule.MinNativeBalance.Sub(currentTRX)
+	if minBalanceTopUp.IsNegative() {
+		minBalanceTopUp = decimal.Zero
+	}
+
+	rawTopUp := bufferedRequired
+	if minBalanceTopUp.GreaterThan(rawTopUp) {
+		rawTopUp = minBalanceTopUp
+	}
+
+	roundedTopUp := decimal.Zero
+	if rawTopUp.IsPositive() {
+		roundedTopUp = rawTopUp.Div(rule.RoundingUnit).Ceil().Mul(rule.RoundingUnit)
+	}
+
+	topUp := roundedTopUp
+	capHit := false
+	if topUp.GreaterThan(rule.MaxTopUp) {
+		topUp = rule.MaxTopUp
+		capHit = true
+	}
+
+	decision = GasTopUpDecision{
+		CurrentBalanceTRX:   currentTRX,
+		EstimatedFeeTRX:     estimatedTRX,
+		RequiredTRX:         required,
+		BufferedRequiredTRX: bufferedRequired,
+		MinBalanceTopUpTRX:  minBalanceTopUp,
+		RawTopUpTRX:         rawTopUp,
+		RoundedTopUpTRX:     roundedTopUp,
+		TopUpTRX:            topUp,
+		CapHit:              capHit,
+		OperationType:       operationType(isContract),
+	}
+
+	if !topUp.IsPositive() {
+		return nil, decision, nil
+	}
+
+	baseUnits := topUp.Mul(tronBaseUnitFactor).Ceil().Truncate(0)
+	return &moneyv1.Money{
+		Currency: strings.ToUpper(nativeCurrency),
+		Amount:   baseUnits.StringFixed(0),
+	}, decision, nil
+}
+
+func tronToTRX(amount *moneyv1.Money) (decimal.Decimal, error) {
+	value, err := decimal.NewFromString(strings.TrimSpace(amount.GetAmount()))
+	if err != nil {
+		return decimal.Zero, err
+	}
+	return value.Div(tronBaseUnitFactor), nil
+}
+
+func operationType(contract bool) string {
+	if contract {
+		return "trc20"
+	}
+	return "native"
+}

api/gateway/chain/internal/service/gateway/driver/tron/gas_topup_test.go

@@ -0,0 +1,147 @@
+package tron
+
+import (
+	"testing"
+
+	"github.com/shopspring/decimal"
+	"github.com/stretchr/testify/require"
+	"github.com/tech/sendico/gateway/chain/internal/service/gateway/shared"
+	"github.com/tech/sendico/gateway/chain/storage/model"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+)
+
+func TestComputeGasTopUp_BalanceSufficient(t *testing.T) {
+	network := tronNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("5"), tronMoney("30"))
+	require.NoError(t, err)
+	require.Nil(t, topUp)
+	require.True(t, decision.TopUpTRX.IsZero())
+}
+
+func TestComputeGasTopUp_BufferedRequired(t *testing.T) {
+	network := tronNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("50"), tronMoney("10"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.Equal(t, "46000000", topUp.GetAmount())
+	require.Equal(t, "TRX", topUp.GetCurrency())
+	require.Equal(t, "46", decision.TopUpTRX.String())
+}
+
+func TestComputeGasTopUp_MinBalanceBinding(t *testing.T) {
+	network := tronNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("5"), tronMoney("1"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.Equal(t, "19000000", topUp.GetAmount())
+	require.Equal(t, "19", decision.TopUpTRX.String())
+}
+
+func TestComputeGasTopUp_RoundsUp(t *testing.T) {
+	policy := shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0),
+			MinNativeBalance: decimal.NewFromFloat(0),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(100),
+		},
+	}
+	network := tronNetwork(&policy)
+	wallet := &model.ManagedWallet{}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("1.1"), tronMoney("0"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.Equal(t, "2000000", topUp.GetAmount())
+	require.Equal(t, "2", decision.TopUpTRX.String())
+}
+
+func TestComputeGasTopUp_CapHit(t *testing.T) {
+	policy := shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0),
+			MinNativeBalance: decimal.NewFromFloat(0),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(10),
+		},
+	}
+	network := tronNetwork(&policy)
+	wallet := &model.ManagedWallet{}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("100"), tronMoney("0"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.Equal(t, "10000000", topUp.GetAmount())
+	require.True(t, decision.CapHit)
+}
+
+func TestComputeGasTopUp_MinBalanceWhenRequiredZero(t *testing.T) {
+	network := tronNetwork(defaultPolicy())
+	wallet := &model.ManagedWallet{}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("0"), tronMoney("5"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.Equal(t, "15000000", topUp.GetAmount())
+	require.Equal(t, "15", decision.TopUpTRX.String())
+}
+
+func TestComputeGasTopUp_ContractPolicyOverride(t *testing.T) {
+	policy := shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0.1),
+			MinNativeBalance: decimal.NewFromFloat(10),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(100),
+		},
+		Contract: &shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0.5),
+			MinNativeBalance: decimal.NewFromFloat(5),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(100),
+		},
+	}
+	network := tronNetwork(&policy)
+	wallet := &model.ManagedWallet{ContractAddress: "0xcontract"}
+
+	topUp, decision, err := ComputeGasTopUp(network, wallet, tronMoney("10"), tronMoney("0"))
+	require.NoError(t, err)
+	require.NotNil(t, topUp)
+	require.Equal(t, "15000000", topUp.GetAmount())
+	require.Equal(t, "15", decision.TopUpTRX.String())
+	require.Equal(t, "trc20", decision.OperationType)
+}
+
+func defaultPolicy() *shared.GasTopUpPolicy {
+	return &shared.GasTopUpPolicy{
+		Default: shared.GasTopUpRule{
+			BufferPercent:    decimal.NewFromFloat(0.15),
+			MinNativeBalance: decimal.NewFromFloat(20),
+			RoundingUnit:     decimal.NewFromFloat(1),
+			MaxTopUp:         decimal.NewFromFloat(500),
+		},
+	}
+}
+
+func tronNetwork(policy *shared.GasTopUpPolicy) shared.Network {
+	return shared.Network{
+		Name:           "tron_mainnet",
+		NativeToken:    "TRX",
+		GasTopUpPolicy: policy,
+	}
+}
+
+func tronMoney(trx string) *moneyv1.Money {
+	value, _ := decimal.NewFromString(trx)
+	baseUnits := value.Mul(tronBaseUnitFactor).Truncate(0)
+	return &moneyv1.Money{
+		Currency: "TRX",
+		Amount:   baseUnits.StringFixed(0),
+	}
+}

api/gateway/chain/internal/service/gateway/executor.go

@@ -81,12 +81,12 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 	client, err := o.clients.Client(network.Name)
 	if err != nil {
-		o.logger.Warn("failed to initialise rpc client", zap.Error(err), zap.String("network", network.Name))
+		o.logger.Warn("Failed to initialise RPC client", zap.Error(err), zap.String("network", network.Name))
 		return "", err
 	}
 	rpcClient, err := o.clients.RPCClient(network.Name)
 	if err != nil {
-		o.logger.Warn("failed to initialise rpc client",
+		o.logger.Warn("Failed to initialise RPC client",
 			zap.String("network", network.Name),
 			zap.Error(err),
 		)
@@ -101,7 +101,7 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 	nonce, err := client.PendingNonceAt(ctx, sourceAddress)
 	if err != nil {
-		o.logger.Warn("failed to fetch nonce", zap.Error(err),
+		o.logger.Warn("Failed to fetch nonce", zap.Error(err),
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.String("wallet_ref", source.WalletRef),
 		)
@@ -110,7 +110,7 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 	gasPrice, err := client.SuggestGasPrice(ctx)
 	if err != nil {
-		o.logger.Warn("failed to suggest gas price",
+		o.logger.Warn("Failed to suggest gas price",
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.String("network", network.Name),
 			zap.Error(err),
@@ -124,12 +124,12 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 	chainID := new(big.Int).SetUint64(network.ChainID)
 
 	if strings.TrimSpace(transfer.ContractAddress) == "" {
-		o.logger.Warn("native token transfer requested but not supported", zap.String("transfer_ref", transfer.TransferRef))
+		o.logger.Warn("Native token transfer requested but not supported", zap.String("transfer_ref", transfer.TransferRef))
 		return "", merrors.NotImplemented("executor: native token transfers not yet supported")
 	}
 
 	if !common.IsHexAddress(transfer.ContractAddress) {
-		o.logger.Warn("invalid token contract address",
+		o.logger.Warn("Invalid token contract address",
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.String("contract", transfer.ContractAddress),
 		)
@@ -139,7 +139,7 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 	decimals, err := erc20Decimals(ctx, rpcClient, tokenAddress)
 	if err != nil {
-		o.logger.Warn("failed to read token decimals", zap.Error(err),
+		o.logger.Warn("Failed to read token decimals", zap.Error(err),
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.String("contract", transfer.ContractAddress),
 		)
@@ -148,12 +148,12 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 	amount := transfer.NetAmount
 	if amount == nil || strings.TrimSpace(amount.Amount) == "" {
-		o.logger.Warn("transfer missing net amount", zap.String("transfer_ref", transfer.TransferRef))
+		o.logger.Warn("Transfer missing net amount", zap.String("transfer_ref", transfer.TransferRef))
 		return "", executorInvalid("transfer missing net amount")
 	}
 	amountInt, err := toBaseUnits(amount.Amount, decimals)
 	if err != nil {
-		o.logger.Warn("failed to convert amount to base units", zap.Error(err),
+		o.logger.Warn("Failed to convert amount to base units", zap.Error(err),
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.String("amount", amount.Amount),
 		)
@@ -177,7 +177,7 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 	}
 	gasLimit, err := client.EstimateGas(ctx, callMsg)
 	if err != nil {
-		o.logger.Warn("failed to estimate gas",
+		o.logger.Warn("Failed to estimate gas",
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.Error(err),
 		)
@@ -188,7 +188,7 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 	signedTx, err := o.keyManager.SignTransaction(ctx, source.KeyReference, tx, chainID)
 	if err != nil {
-		o.logger.Warn("failed to sign transaction", zap.Error(err),
+		o.logger.Warn("Failed to sign transaction", zap.Error(err),
 			zap.String("transfer_ref", transfer.TransferRef),
 			zap.String("wallet_ref", source.WalletRef),
 		)
@@ -196,14 +196,14 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 	}
 
 	if err := client.SendTransaction(ctx, signedTx); err != nil {
-		o.logger.Warn("failed to send transaction", zap.Error(err),
+		o.logger.Warn("Failed to send transaction", zap.Error(err),
 			zap.String("transfer_ref", transfer.TransferRef),
 		)
 		return "", executorInternal("failed to send transaction", err)
 	}
 
 	txHash = signedTx.Hash().Hex()
-	o.logger.Info("transaction submitted",
+	o.logger.Info("Transaction submitted",
 		zap.String("transfer_ref", transfer.TransferRef),
 		zap.String("tx_hash", txHash),
 		zap.String("network", network.Name),
@@ -214,12 +214,12 @@ func (o *onChainExecutor) SubmitTransfer(ctx context.Context, transfer *model.Tr
 
 func (o *onChainExecutor) AwaitConfirmation(ctx context.Context, network shared.Network, txHash string) (*types.Receipt, error) {
 	if strings.TrimSpace(txHash) == "" {
-		o.logger.Warn("missing transaction hash for confirmation", zap.String("network", network.Name))
+		o.logger.Warn("Missing transaction hash for confirmation", zap.String("network", network.Name))
 		return nil, executorInvalid("tx hash is required")
 	}
 	rpcURL := strings.TrimSpace(network.RPCURL)
 	if rpcURL == "" {
-		o.logger.Warn("network rpc url missing while awaiting confirmation", zap.String("tx_hash", txHash))
+		o.logger.Warn("Network RPC url missing while awaiting confirmation", zap.String("tx_hash", txHash))
 		return nil, executorInvalid("network rpc url is not configured")
 	}
 
@@ -238,27 +238,27 @@ func (o *onChainExecutor) AwaitConfirmation(ctx context.Context, network shared.
 			if errors.Is(err, ethereum.NotFound) {
 				select {
 				case <-ticker.C:
-					o.logger.Debug("transaction not yet mined",
+					o.logger.Debug("Transaction not yet mined",
 						zap.String("tx_hash", txHash),
 						zap.String("network", network.Name),
 					)
 					continue
 				case <-ctx.Done():
-					o.logger.Warn("context cancelled while awaiting confirmation",
+					o.logger.Warn("Context cancelled while awaiting confirmation",
 						zap.String("tx_hash", txHash),
 						zap.String("network", network.Name),
 					)
 					return nil, ctx.Err()
 				}
 			}
-			o.logger.Warn("failed to fetch transaction receipt",
+			o.logger.Warn("Failed to fetch transaction receipt",
 				zap.String("tx_hash", txHash),
 				zap.String("network", network.Name),
 				zap.Error(err),
 			)
 			return nil, executorInternal("failed to fetch transaction receipt", err)
 		}
-		o.logger.Info("transaction confirmed",
+		o.logger.Info("Transaction confirmed",
 			zap.String("tx_hash", txHash),
 			zap.String("network", network.Name),
 			zap.Uint64("block_number", receipt.BlockNumber.Uint64()),

api/gateway/chain/internal/service/gateway/rpcclient/clients.go

@@ -2,6 +2,7 @@ package rpcclient
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -70,7 +71,7 @@ func Prepare(ctx context.Context, logger mlogger.Logger, networks []shared.Netwo
 		cancel()
 		if err != nil {
 			result.Close()
-			clientLogger.Warn("failed to dial rpc endpoint", append(fields, zap.Error(err))...)
+			clientLogger.Warn("Failed to dial rpc endpoint", append(fields, zap.Error(err))...)
 			return nil, merrors.Internal(fmt.Sprintf("rpc dial failed for %s: %s", name, err.Error()))
 		}
 		client := ethclient.NewClient(rpcCli)
@@ -78,7 +79,7 @@ func Prepare(ctx context.Context, logger mlogger.Logger, networks []shared.Netwo
 			eth: client,
 			rpc: rpcCli,
 		}
-		clientLogger.Info("rpc client ready", fields...)
+		clientLogger.Info("RPC client ready", fields...)
 	}
 
 	if len(result.clients) == 0 {
@@ -94,12 +95,12 @@ func Prepare(ctx context.Context, logger mlogger.Logger, networks []shared.Netwo
 // Client returns a prepared client for the given network name.
 func (c *Clients) Client(network string) (*ethclient.Client, error) {
 	if c == nil {
-		return nil, merrors.Internal("rpc clients not initialised")
+		return nil, merrors.Internal("RPC clients not initialised")
 	}
 	name := strings.ToLower(strings.TrimSpace(network))
 	entry, ok := c.clients[name]
 	if !ok || entry.eth == nil {
-		return nil, merrors.InvalidArgument(fmt.Sprintf("rpc client not configured for network %s", name))
+		return nil, merrors.InvalidArgument(fmt.Sprintf("RPC client not configured for network %s", name))
 	}
 	return entry.eth, nil
 }
@@ -129,7 +130,7 @@ func (c *Clients) Close() {
 			entry.eth.Close()
 		}
 		if c.logger != nil {
-			c.logger.Info("rpc client closed", zap.String("network", name))
+			c.logger.Info("RPC client closed", zap.String("network", name))
 		}
 	}
 }
@@ -155,16 +156,15 @@ func (l *loggingRoundTripper) RoundTrip(req *http.Request) (*http.Response, erro
 
 	fields := []zap.Field{
 		zap.String("network", l.network),
-		zap.String("rpc_endpoint", l.endpoint),
 	}
 	if len(reqBody) > 0 {
 		fields = append(fields, zap.String("rpc_request", truncate(string(reqBody), 2048)))
 	}
-	l.logger.Debug("rpc request", fields...)
+	l.logger.Debug("RPC request", fields...)
 
 	resp, err := l.base.RoundTrip(req)
 	if err != nil {
-		l.logger.Warn("rpc http request failed", append(fields, zap.Error(err))...)
+		l.logger.Warn("RPC http request failed", append(fields, zap.Error(err))...)
 		return nil, err
 	}
 
@@ -175,11 +175,19 @@ func (l *loggingRoundTripper) RoundTrip(req *http.Request) (*http.Response, erro
 	respFields := append(fields,
 		zap.Int("status_code", resp.StatusCode),
 	)
+	if contentType := strings.TrimSpace(resp.Header.Get("Content-Type")); contentType != "" {
+		respFields = append(respFields, zap.String("content_type", contentType))
+	}
 	if len(bodyBytes) > 0 {
 		respFields = append(respFields, zap.String("rpc_response", truncate(string(bodyBytes), 2048)))
 	}
+	l.logger.Debug("RPC response", respFields...)
 	if resp.StatusCode >= 400 {
 		l.logger.Warn("RPC response error", respFields...)
+	} else if len(bodyBytes) == 0 {
+		l.logger.Warn("RPC response empty body", respFields...)
+	} else if len(bodyBytes) > 0 && !json.Valid(bodyBytes) {
+		l.logger.Warn("RPC response invalid JSON", respFields...)
 	}
 
 	return resp, nil

api/gateway/chain/internal/service/gateway/service.go

@@ -126,6 +126,14 @@ func (s *Service) EstimateTransferFee(ctx context.Context, req *chainv1.Estimate
 	return executeUnary(ctx, s, "EstimateTransferFee", s.commands.EstimateTransfer.Execute, req)
 }
 
+func (s *Service) ComputeGasTopUp(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) (*chainv1.ComputeGasTopUpResponse, error) {
+	return executeUnary(ctx, s, "ComputeGasTopUp", s.commands.ComputeGasTopUp.Execute, req)
+}
+
+func (s *Service) EnsureGasTopUp(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) (*chainv1.EnsureGasTopUpResponse, error) {
+	return executeUnary(ctx, s, "EnsureGasTopUp", s.commands.EnsureGasTopUp.Execute, req)
+}
+
 func (s *Service) ensureRepository(ctx context.Context) error {
 	if s.storage == nil {
 		return errStorageUnavailable

api/gateway/chain/internal/service/gateway/service_test.go

@@ -66,6 +66,25 @@ func TestCreateManagedWallet_Idempotent(t *testing.T) {
 	require.Equal(t, 1, repo.wallets.count())
 }
 
+func TestCreateManagedWallet_NativeTokenWithoutContract(t *testing.T) {
+	svc, _ := newTestService(t)
+	ctx := context.Background()
+
+	resp, err := svc.CreateManagedWallet(ctx, &ichainv1.CreateManagedWalletRequest{
+		IdempotencyKey:  "idem-native",
+		OrganizationRef: "org-1",
+		OwnerRef:        "owner-1",
+		Asset: &ichainv1.Asset{
+			Chain:       ichainv1.ChainNetwork_CHAIN_NETWORK_ETHEREUM_MAINNET,
+			TokenSymbol: "ETH",
+		},
+	})
+	require.NoError(t, err)
+	require.NotNil(t, resp.GetWallet())
+	require.Equal(t, "ETH", resp.GetWallet().GetAsset().GetTokenSymbol())
+	require.Empty(t, resp.GetWallet().GetAsset().GetContractAddress())
+}
+
 func TestSubmitTransfer_ManagedDestination(t *testing.T) {
 	svc, repo := newTestService(t)
 	ctx := context.Background()
@@ -144,6 +163,37 @@ func TestGetWalletBalance_NotFound(t *testing.T) {
 	require.Equal(t, codes.NotFound, st.Code())
 }
 
+func TestGetWalletBalance_ReturnsCachedNativeAvailable(t *testing.T) {
+	svc, repo := newTestService(t)
+	ctx := context.Background()
+
+	createResp, err := svc.CreateManagedWallet(ctx, &ichainv1.CreateManagedWalletRequest{
+		IdempotencyKey:  "idem-balance",
+		OrganizationRef: "org-1",
+		OwnerRef:        "owner-1",
+		Asset: &ichainv1.Asset{
+			Chain:       ichainv1.ChainNetwork_CHAIN_NETWORK_ETHEREUM_MAINNET,
+			TokenSymbol: "USDC",
+		},
+	})
+	require.NoError(t, err)
+	walletRef := createResp.GetWallet().GetWalletRef()
+
+	err = repo.wallets.SaveBalance(ctx, &model.WalletBalance{
+		WalletRef:       walletRef,
+		Available:       &moneyv1.Money{Currency: "USDC", Amount: "25"},
+		NativeAvailable: &moneyv1.Money{Currency: "ETH", Amount: "0.5"},
+		CalculatedAt:    time.Now().UTC(),
+	})
+	require.NoError(t, err)
+
+	resp, err := svc.GetWalletBalance(ctx, &ichainv1.GetWalletBalanceRequest{WalletRef: walletRef})
+	require.NoError(t, err)
+	require.NotNil(t, resp.GetBalance())
+	require.Equal(t, "0.5", resp.GetBalance().GetNativeAvailable().GetAmount())
+	require.Equal(t, "ETH", resp.GetBalance().GetNativeAvailable().GetCurrency())
+}
+
 // ---- in-memory storage implementation ----
 
 type inMemoryRepository struct {
@@ -531,7 +581,8 @@ func newTestService(t *testing.T) (*Service, *inMemoryRepository) {
 	repo := newInMemoryRepository()
 	logger := zap.NewNop()
 	networks := []shared.Network{{
-		Name: "ethereum_mainnet",
+		Name:        "ethereum_mainnet",
+		NativeToken: "ETH",
 		TokenConfigs: []shared.TokenContract{
 			{Symbol: "USDC", ContractAddress: "0xusdc"},
 		},

api/gateway/chain/internal/service/gateway/shared/gas_topup.go

@@ -0,0 +1,32 @@
+package shared
+
+import "github.com/shopspring/decimal"
+
+// GasTopUpRule defines buffer, minimum, rounding, and cap behavior for native gas top-ups.
+type GasTopUpRule struct {
+	BufferPercent    decimal.Decimal
+	MinNativeBalance decimal.Decimal
+	RoundingUnit     decimal.Decimal
+	MaxTopUp         decimal.Decimal
+}
+
+// GasTopUpPolicy captures default and optional overrides for native vs contract transfers.
+type GasTopUpPolicy struct {
+	Default  GasTopUpRule
+	Native   *GasTopUpRule
+	Contract *GasTopUpRule
+}
+
+// Rule selects the policy rule for the transfer type.
+func (p *GasTopUpPolicy) Rule(contractTransfer bool) (GasTopUpRule, bool) {
+	if p == nil {
+		return GasTopUpRule{}, false
+	}
+	if contractTransfer && p.Contract != nil {
+		return *p.Contract, true
+	}
+	if !contractTransfer && p.Native != nil {
+		return *p.Native, true
+	}
+	return p.Default, true
+}

api/gateway/chain/internal/service/gateway/shared/helpers.go

@@ -119,13 +119,23 @@ func TransferStatusToProto(status model.TransferStatus) chainv1.TransferStatus {
 	}
 }
 
+// NativeCurrency returns the canonical native token symbol for a network.
+func NativeCurrency(network Network) string {
+	currency := strings.ToUpper(strings.TrimSpace(network.NativeToken))
+	if currency == "" {
+		currency = strings.ToUpper(strings.TrimSpace(network.Name))
+	}
+	return currency
+}
+
 // Network describes a supported blockchain network and known token contracts.
 type Network struct {
-	Name         string
-	RPCURL       string
-	ChainID      uint64
-	NativeToken  string
-	TokenConfigs []TokenContract
+	Name           string
+	RPCURL         string
+	ChainID        uint64
+	NativeToken    string
+	TokenConfigs   []TokenContract
+	GasTopUpPolicy *GasTopUpPolicy
 }
 
 // TokenContract captures the metadata needed to work with a specific on-chain token.

api/gateway/chain/internal/service/gateway/transfer_execution.go

@@ -24,7 +24,7 @@ func (s *Service) launchTransferExecution(transferRef, sourceWalletRef string, n
 		defer cancel()
 
 		if err := s.executeTransfer(ctx, ref, walletRef, net); err != nil {
-			s.logger.Warn("failed to execute transfer", zap.String("transfer_ref", ref), zap.Error(err))
+			s.logger.Warn("Failed to execute transfer", zap.String("transfer_ref", ref), zap.Error(err))
 		}
 	}(transferRef, sourceWalletRef, network)
 }
@@ -57,6 +57,23 @@ func (s *Service) executeTransfer(ctx context.Context, transferRef, sourceWallet
 		return err
 	}
 
+	sourceAddress, err := chainDriver.NormalizeAddress(sourceWallet.DepositAddress)
+	if err != nil {
+		_, _ = s.storage.Transfers().UpdateStatus(ctx, transferRef, model.TransferStatusFailed, err.Error(), "")
+		return err
+	}
+	if chainDriver.Name() == "tron" && sourceAddress == destinationAddress {
+		s.logger.Info("Self transfer detected; skipping submission",
+			zap.String("transfer_ref", transferRef),
+			zap.String("wallet_ref", sourceWalletRef),
+			zap.String("network", network.Name),
+		)
+		if _, err := s.storage.Transfers().UpdateStatus(ctx, transferRef, model.TransferStatusConfirmed, "", ""); err != nil {
+			s.logger.Warn("Failed to update transfer status to confirmed", zap.String("transfer_ref", transferRef), zap.Error(err))
+		}
+		return nil
+	}
+
 	txHash, err := chainDriver.SubmitTransfer(ctx, driverDeps, network, transfer, sourceWallet, destinationAddress)
 	if err != nil {
 		_, _ = s.storage.Transfers().UpdateStatus(ctx, transferRef, model.TransferStatusFailed, err.Error(), "")

api/gateway/chain/storage/model/wallet.go

@@ -47,6 +47,7 @@ type WalletBalance struct {
 
 	WalletRef       string         `bson:"walletRef" json:"walletRef"`
 	Available       *moneyv1.Money `bson:"available" json:"available"`
+	NativeAvailable *moneyv1.Money `bson:"nativeAvailable,omitempty" json:"nativeAvailable,omitempty"`
 	PendingInbound  *moneyv1.Money `bson:"pendingInbound,omitempty" json:"pendingInbound,omitempty"`
 	PendingOutbound *moneyv1.Money `bson:"pendingOutbound,omitempty" json:"pendingOutbound,omitempty"`
 	CalculatedAt    time.Time      `bson:"calculatedAt" json:"calculatedAt"`

api/gateway/chain/storage/mongo/store/wallets.go

@@ -99,24 +99,49 @@ func (w *Wallets) Create(ctx context.Context, wallet *model.ManagedWallet) (*mod
 	if strings.TrimSpace(wallet.IdempotencyKey) == "" {
 		return nil, merrors.InvalidArgument("walletsStore: empty idempotencyKey")
 	}
+	fields := []zap.Field{
+		zap.String("wallet_ref", wallet.WalletRef),
+		zap.String("idempotency_key", wallet.IdempotencyKey),
+	}
+	if wallet.OrganizationRef != "" {
+		fields = append(fields, zap.String("organization_ref", wallet.OrganizationRef))
+	}
+	if wallet.OwnerRef != "" {
+		fields = append(fields, zap.String("owner_ref", wallet.OwnerRef))
+	}
+	if wallet.Network != "" {
+		fields = append(fields, zap.String("network", wallet.Network))
+	}
+	if wallet.TokenSymbol != "" {
+		fields = append(fields, zap.String("token_symbol", wallet.TokenSymbol))
+	}
 	if err := w.walletRepo.Insert(ctx, wallet, repository.Filter("idempotencyKey", wallet.IdempotencyKey)); err != nil {
 		if errors.Is(err, merrors.ErrDataConflict) {
-			w.logger.Debug("wallet already exists", zap.String("wallet_ref", wallet.WalletRef), zap.String("idempotency_key", wallet.IdempotencyKey))
+			w.logger.Debug("wallet already exists", fields...)
 			return wallet, nil
 		}
+		w.logger.Warn("wallet create failed", append(fields, zap.Error(err))...)
 		return nil, err
 	}
-	w.logger.Debug("wallet created", zap.String("wallet_ref", wallet.WalletRef))
+	w.logger.Debug("wallet created", fields...)
 	return wallet, nil
 }
 
-func (w *Wallets) Get(ctx context.Context, walletRef string) (*model.ManagedWallet, error) {
-	walletRef = strings.TrimSpace(walletRef)
-	if walletRef == "" {
+func (w *Wallets) Get(ctx context.Context, walletID string) (*model.ManagedWallet, error) {
+	walletID = strings.TrimSpace(walletID)
+	if walletID == "" {
 		return nil, merrors.InvalidArgument("walletsStore: empty walletRef")
 	}
+	fields := []zap.Field{
+		zap.String("wallet_id", walletID),
+	}
 	wallet := &model.ManagedWallet{}
-	if err := w.walletRepo.FindOneByFilter(ctx, repository.Filter("walletRef", walletRef), wallet); err != nil {
+	if err := w.balanceRepo.FindOneByFilter(ctx, repository.Filter("walletRef", walletID), wallet); err != nil {
+		if errors.Is(err, merrors.ErrNoData) {
+			w.logger.Debug("wallet not found", fields...)
+		} else {
+			w.logger.Warn("wallet lookup failed", append(fields, zap.Error(err))...)
+		}
 		return nil, err
 	}
 	return wallet, nil
@@ -124,29 +149,38 @@ func (w *Wallets) Get(ctx context.Context, walletRef string) (*model.ManagedWall
 
 func (w *Wallets) List(ctx context.Context, filter model.ManagedWalletFilter) (*model.ManagedWalletList, error) {
 	query := repository.Query()
+	fields := make([]zap.Field, 0, 6)
 
 	if org := strings.TrimSpace(filter.OrganizationRef); org != "" {
 		query = query.Filter(repository.Field("organizationRef"), org)
+		fields = append(fields, zap.String("organization_ref", org))
 	}
 	if owner := strings.TrimSpace(filter.OwnerRef); owner != "" {
 		query = query.Filter(repository.Field("ownerRef"), owner)
+		fields = append(fields, zap.String("owner_ref", owner))
 	}
 	if network := strings.TrimSpace(filter.Network); network != "" {
-		query = query.Filter(repository.Field("network"), strings.ToLower(network))
+		normalized := strings.ToLower(network)
+		query = query.Filter(repository.Field("network"), normalized)
+		fields = append(fields, zap.String("network", normalized))
 	}
 	if token := strings.TrimSpace(filter.TokenSymbol); token != "" {
-		query = query.Filter(repository.Field("tokenSymbol"), strings.ToUpper(token))
+		normalized := strings.ToUpper(token)
+		query = query.Filter(repository.Field("tokenSymbol"), normalized)
+		fields = append(fields, zap.String("token_symbol", normalized))
 	}
 
 	if cursor := strings.TrimSpace(filter.Cursor); cursor != "" {
 		if oid, err := primitive.ObjectIDFromHex(cursor); err == nil {
 			query = query.Comparison(repository.IDField(), builder.Gt, oid)
+			fields = append(fields, zap.String("cursor", cursor))
 		} else {
 			w.logger.Warn("ignoring invalid wallet cursor", zap.String("cursor", cursor), zap.Error(err))
 		}
 	}
 
 	limit := sanitizeWalletLimit(filter.Limit)
+	fields = append(fields, zap.Int64("limit", limit))
 	fetchLimit := limit + 1
 	query = query.Sort(repository.IDField(), true).Limit(&fetchLimit)
 
@@ -160,8 +194,10 @@ func (w *Wallets) List(ctx context.Context, filter model.ManagedWalletFilter) (*
 		return nil
 	}
 
-	if err := w.walletRepo.FindManyByFilter(ctx, query, decoder); err != nil && !errors.Is(err, merrors.ErrNoData) {
-		return nil, err
+	listErr := w.walletRepo.FindManyByFilter(ctx, query, decoder)
+	if listErr != nil && !errors.Is(listErr, merrors.ErrNoData) {
+		w.logger.Warn("wallet list failed", append(fields, zap.Error(listErr))...)
+		return nil, listErr
 	}
 
 	nextCursor := ""
@@ -171,10 +207,21 @@ func (w *Wallets) List(ctx context.Context, filter model.ManagedWalletFilter) (*
 		wallets = wallets[:len(wallets)-1]
 	}
 
-	return &model.ManagedWalletList{
+	result := &model.ManagedWalletList{
 		Items:      wallets,
 		NextCursor: nextCursor,
-	}, nil
+	}
+
+	fields = append(fields,
+		zap.Int("count", len(result.Items)),
+		zap.String("next_cursor", result.NextCursor),
+	)
+	if errors.Is(listErr, merrors.ErrNoData) {
+		w.logger.Debug("wallet list empty", fields...)
+	} else {
+		w.logger.Debug("wallet list fetched", fields...)
+	}
+	return result, nil
 }
 
 func (w *Wallets) SaveBalance(ctx context.Context, balance *model.WalletBalance) error {
@@ -188,6 +235,7 @@ func (w *Wallets) SaveBalance(ctx context.Context, balance *model.WalletBalance)
 	if balance.CalculatedAt.IsZero() {
 		balance.CalculatedAt = time.Now().UTC()
 	}
+	fields := []zap.Field{zap.String("wallet_ref", balance.WalletRef)}
 
 	existing := &model.WalletBalance{}
 	err := w.balanceRepo.FindOneByFilter(ctx, repository.Filter("walletRef", balance.WalletRef), existing)
@@ -198,28 +246,40 @@ func (w *Wallets) SaveBalance(ctx context.Context, balance *model.WalletBalance)
 		existing.PendingOutbound = balance.PendingOutbound
 		existing.CalculatedAt = balance.CalculatedAt
 		if err := w.balanceRepo.Update(ctx, existing); err != nil {
+			w.logger.Warn("wallet balance update failed", append(fields, zap.Error(err))...)
 			return err
 		}
+		w.logger.Debug("wallet balance updated", fields...)
 		return nil
 	case errors.Is(err, merrors.ErrNoData):
 		if err := w.balanceRepo.Insert(ctx, balance, repository.Filter("walletRef", balance.WalletRef)); err != nil {
+			w.logger.Warn("wallet balance create failed", append(fields, zap.Error(err))...)
 			return err
 		}
+		w.logger.Debug("wallet balance created", fields...)
 		return nil
 	default:
+		w.logger.Warn("wallet balance lookup failed", append(fields, zap.Error(err))...)
 		return err
 	}
 }
 
-func (w *Wallets) GetBalance(ctx context.Context, walletRef string) (*model.WalletBalance, error) {
-	walletRef = strings.TrimSpace(walletRef)
-	if walletRef == "" {
+func (w *Wallets) GetBalance(ctx context.Context, walletID string) (*model.WalletBalance, error) {
+	walletID = strings.TrimSpace(walletID)
+	if walletID == "" {
 		return nil, merrors.InvalidArgument("walletsStore: empty walletRef")
 	}
+	fields := []zap.Field{zap.String("wallet_ref", walletID)}
 	balance := &model.WalletBalance{}
-	if err := w.balanceRepo.FindOneByFilter(ctx, repository.Filter("walletRef", walletRef), balance); err != nil {
+	if err := w.balanceRepo.FindOneByFilter(ctx, repository.Filter("walletRef", walletID), balance); err != nil {
+		if errors.Is(err, merrors.ErrNoData) {
+			w.logger.Debug("wallet balance not found", fields...)
+		} else {
+			w.logger.Warn("wallet balance lookup failed", append(fields, zap.Error(err))...)
+		}
 		return nil, err
 	}
+	w.logger.Debug("wallet balance fetched", fields...)
 	return balance, nil
 }
 

api/gateway/mntx/config.yml

@@ -26,7 +26,7 @@ monetix:
   base_url_env: MONETIX_BASE_URL
   project_id_env: MONETIX_PROJECT_ID
   secret_key_env: MONETIX_SECRET_KEY
-  allowed_currencies: ["USD", "EUR"]
+  allowed_currencies: ["RUB"]
   require_customer_address: false
   request_timeout_seconds: 15
   status_success: "success"

api/payments/orchestrator/config.yml

@@ -51,6 +51,12 @@ gateway:
   call_timeout_seconds: 3
   insecure: true
 
+mntx:
+  address: "sendico_mntx_gateway:50075"
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 3
+  insecure: true
+
 oracle:
   address: "sendico_fx_oracle:50051"
   dial_timeout_seconds: 5
@@ -59,8 +65,8 @@ oracle:
 
 card_gateways:
   monetix:
-    funding_address: "wallet_funding_monetix"
-    fee_address: "wallet_fee_monetix"
+    funding_address: "TGBDXEg9rxSqGFJDcb889zqTjDwx1bmLRF"
+    fee_wallet_ref: "694c124ed76f9f811ac57133"
 
 fee_ledger_accounts:
   monetix: "ledger:fees:monetix"

api/payments/orchestrator/internal/server/internal/serverimp.go

@@ -9,6 +9,7 @@ import (
 
 	oracleclient "github.com/tech/sendico/fx/oracle/client"
 	chainclient "github.com/tech/sendico/gateway/chain/client"
+	mntxclient "github.com/tech/sendico/gateway/mntx/client"
 	ledgerclient "github.com/tech/sendico/ledger/client"
 	"github.com/tech/sendico/payments/orchestrator/internal/service/orchestrator"
 	"github.com/tech/sendico/payments/orchestrator/storage"
@@ -36,6 +37,7 @@ type Imp struct {
 	feesConn      *grpc.ClientConn
 	ledgerClient  ledgerclient.Client
 	gatewayClient chainclient.Client
+	mntxClient    mntxclient.Client
 	oracleClient  oracleclient.Client
 }
 
@@ -44,6 +46,7 @@ type config struct {
 	Fees            clientConfig                      `yaml:"fees"`
 	Ledger          clientConfig                      `yaml:"ledger"`
 	Gateway         clientConfig                      `yaml:"gateway"`
+	Mntx            clientConfig                      `yaml:"mntx"`
 	Oracle          clientConfig                      `yaml:"oracle"`
 	CardGateways    map[string]cardGatewayRouteConfig `yaml:"card_gateways"`
 	FeeAccounts     map[string]string                 `yaml:"fee_ledger_accounts"`
@@ -59,6 +62,7 @@ type clientConfig struct {
 type cardGatewayRouteConfig struct {
 	FundingAddress string `yaml:"funding_address"`
 	FeeAddress     string `yaml:"fee_address"`
+	FeeWalletRef   string `yaml:"fee_wallet_ref"`
 }
 
 func (c clientConfig) address() string {
@@ -104,6 +108,9 @@ func (i *Imp) Shutdown() {
 	if i.gatewayClient != nil {
 		_ = i.gatewayClient.Close()
 	}
+	if i.mntxClient != nil {
+		_ = i.mntxClient.Close()
+	}
 	if i.oracleClient != nil {
 		_ = i.oracleClient.Close()
 	}
@@ -138,6 +145,11 @@ func (i *Imp) Start() error {
 		i.gatewayClient = gatewayClient
 	}
 
+	mntxClient := i.initMntxClient(cfg.Mntx)
+	if mntxClient != nil {
+		i.mntxClient = mntxClient
+	}
+
 	oracleClient := i.initOracleClient(cfg.Oracle)
 	if oracleClient != nil {
 		i.oracleClient = oracleClient
@@ -154,6 +166,9 @@ func (i *Imp) Start() error {
 		if gatewayClient != nil {
 			opts = append(opts, orchestrator.WithChainGatewayClient(gatewayClient))
 		}
+		if mntxClient != nil {
+			opts = append(opts, orchestrator.WithMntxGateway(mntxClient))
+		}
 		if oracleClient != nil {
 			opts = append(opts, orchestrator.WithOracleClient(oracleClient))
 		}
@@ -191,11 +206,11 @@ func (i *Imp) initFeesClient(cfg clientConfig) (feesv1.FeeEngineClient, *grpc.Cl
 
 	conn, err := grpc.DialContext(dialCtx, addr, grpc.WithTransportCredentials(creds))
 	if err != nil {
-		i.logger.Warn("failed to connect to fees service", zap.String("address", addr), zap.Error(err))
+		i.logger.Warn("Failed to connect to fees service", zap.String("address", addr), zap.Error(err))
 		return nil, nil
 	}
 
-	i.logger.Info("connected to fees service", zap.String("address", addr))
+	i.logger.Info("Connected to fees service", zap.String("address", addr))
 	return feesv1.NewFeeEngineClient(conn), conn
 }
 
@@ -215,10 +230,10 @@ func (i *Imp) initLedgerClient(cfg clientConfig) ledgerclient.Client {
 		Insecure:    cfg.InsecureTransport,
 	})
 	if err != nil {
-		i.logger.Warn("failed to connect to ledger service", zap.String("address", addr), zap.Error(err))
+		i.logger.Warn("Failed to connect to ledger service", zap.String("address", addr), zap.Error(err))
 		return nil
 	}
-	i.logger.Info("connected to ledger service", zap.String("address", addr))
+	i.logger.Info("Connected to ledger service", zap.String("address", addr))
 	return client
 }
 
@@ -245,6 +260,28 @@ func (i *Imp) initGatewayClient(cfg clientConfig) chainclient.Client {
 	return client
 }
 
+func (i *Imp) initMntxClient(cfg clientConfig) mntxclient.Client {
+	addr := cfg.address()
+	if addr == "" {
+		return nil
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), cfg.dialTimeout())
+	defer cancel()
+
+	client, err := mntxclient.New(ctx, mntxclient.Config{
+		Address:     addr,
+		DialTimeout: cfg.dialTimeout(),
+		CallTimeout: cfg.callTimeout(),
+	})
+	if err != nil {
+		i.logger.Warn("Failed to connect to mntx gateway service", zap.String("address", addr), zap.Error(err))
+		return nil
+	}
+	i.logger.Info("Connected to mntx gateway service", zap.String("address", addr))
+	return client
+}
+
 func (i *Imp) initOracleClient(cfg clientConfig) oracleclient.Client {
 	addr := cfg.address()
 	if addr == "" {
@@ -261,10 +298,10 @@ func (i *Imp) initOracleClient(cfg clientConfig) oracleclient.Client {
 		Insecure:    cfg.InsecureTransport,
 	})
 	if err != nil {
-		i.logger.Warn("failed to connect to oracle service", zap.String("address", addr), zap.Error(err))
+		i.logger.Warn("Failed to connect to oracle service", zap.String("address", addr), zap.Error(err))
 		return nil
 	}
-	i.logger.Info("connected to oracle service", zap.String("address", addr))
+	i.logger.Info("Connected to oracle service", zap.String("address", addr))
 	return client
 }
 
@@ -323,6 +360,7 @@ func buildCardGatewayRoutes(src map[string]cardGatewayRouteConfig) map[string]or
 		result[trimmedKey] = orchestrator.CardGatewayRoute{
 			FundingAddress: strings.TrimSpace(route.FundingAddress),
 			FeeAddress:     strings.TrimSpace(route.FeeAddress),
+			FeeWalletRef:   strings.TrimSpace(route.FeeWalletRef),
 		}
 	}
 	return result

api/payments/orchestrator/internal/service/orchestrator/card_payout.go

@@ -7,13 +7,21 @@ import (
 	"github.com/shopspring/decimal"
 	"github.com/tech/sendico/payments/orchestrator/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
 	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
 	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 	"go.uber.org/zap"
 )
 
-const defaultCardGateway = "monetix"
+const (
+	defaultCardGateway = "monetix"
+
+	stepCodeGasTopUp        = "gas_top_up"
+	stepCodeFundingTransfer = "funding_transfer"
+	stepCodeCardPayout      = "card_payout"
+	stepCodeFeeTransfer     = "fee_transfer"
+)
 
 func (s *Service) cardRoute(gateway string) (CardGatewayRoute, error) {
 	if len(s.deps.cardRoutes) == 0 {
@@ -54,24 +62,214 @@ func (s *Service) submitCardFundingTransfers(ctx context.Context, payment *model
 	if err != nil {
 		return err
 	}
+	sourceWalletRef := strings.TrimSpace(source.ManagedWalletRef)
+	fundingAddress := strings.TrimSpace(route.FundingAddress)
+	feeWalletRef := strings.TrimSpace(route.FeeWalletRef)
 
 	amount := cloneMoney(intent.Amount)
-	if amount == nil {
+	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
 		return merrors.InvalidArgument("card funding: amount is required")
 	}
 
+	payoutAmount, err := cardPayoutAmount(payment)
+	if err != nil {
+		return err
+	}
+
+	feeMoney := (*moneyv1.Money)(nil)
+	if quote != nil {
+		feeMoney = quote.GetExpectedFeeTotal()
+	}
+	if feeMoney == nil && payment.LastQuote != nil {
+		feeMoney = payment.LastQuote.ExpectedFeeTotal
+	}
+	feeDecimal := decimal.Zero
+	if feeMoney != nil && strings.TrimSpace(feeMoney.GetAmount()) != "" {
+		if strings.TrimSpace(feeMoney.GetCurrency()) == "" {
+			return merrors.InvalidArgument("card funding: fee currency is required")
+		}
+		feeDecimal, err = decimalFromMoney(feeMoney)
+		if err != nil {
+			return err
+		}
+	}
+	feeRequired := feeDecimal.IsPositive()
+
+	fundingDest := &chainv1.TransferDestination{
+		Destination: &chainv1.TransferDestination_ExternalAddress{ExternalAddress: fundingAddress},
+	}
+	fundingFee, err := s.estimateTransferNetworkFee(ctx, sourceWalletRef, fundingDest, amount)
+	if err != nil {
+		return err
+	}
+
+	var feeTransferFee *moneyv1.Money
+	if feeRequired {
+		if feeWalletRef == "" {
+			return merrors.InvalidArgument("card funding: fee wallet ref is required when fee exists")
+		}
+		feeDest := &chainv1.TransferDestination{
+			Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: feeWalletRef},
+		}
+		feeTransferFee, err = s.estimateTransferNetworkFee(ctx, sourceWalletRef, feeDest, feeMoney)
+		if err != nil {
+			return err
+		}
+	}
+
+	totalFee, gasCurrency, err := sumNetworkFees(fundingFee, feeTransferFee)
+	if err != nil {
+		return err
+	}
+
+	var estimatedTotalFee *moneyv1.Money
+	if gasCurrency != "" && !totalFee.IsNegative() {
+		estimatedTotalFee = makeMoney(gasCurrency, totalFee)
+	}
+
+	var topUpMoney *moneyv1.Money
+	var topUpFee *moneyv1.Money
+	topUpPositive := false
+	if estimatedTotalFee != nil {
+		computeResp, err := s.deps.gateway.client.ComputeGasTopUp(ctx, &chainv1.ComputeGasTopUpRequest{
+			WalletRef:         sourceWalletRef,
+			EstimatedTotalFee: estimatedTotalFee,
+		})
+		if err != nil {
+			s.logger.Warn("card funding gas top-up compute failed", zap.Error(err), zap.String("payment_ref", payment.PaymentRef))
+			return err
+		}
+		if computeResp != nil {
+			topUpMoney = computeResp.GetTopupAmount()
+		}
+		if topUpMoney != nil && strings.TrimSpace(topUpMoney.GetAmount()) != "" {
+			amountDec, err := decimalFromMoney(topUpMoney)
+			if err != nil {
+				return err
+			}
+			topUpPositive = amountDec.IsPositive()
+		}
+		if topUpMoney != nil && topUpPositive {
+			if strings.TrimSpace(topUpMoney.GetCurrency()) == "" {
+				return merrors.InvalidArgument("card funding: gas top-up currency is required")
+			}
+			if feeWalletRef == "" {
+				return merrors.InvalidArgument("card funding: fee wallet ref is required for gas top-up")
+			}
+			topUpDest := &chainv1.TransferDestination{
+				Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: sourceWalletRef},
+			}
+			topUpFee, err = s.estimateTransferNetworkFee(ctx, feeWalletRef, topUpDest, topUpMoney)
+			if err != nil {
+				return err
+			}
+		}
+	}
+
+	plan := ensureExecutionPlan(payment)
+	var gasStep *model.ExecutionStep
+	if topUpMoney != nil && topUpPositive {
+		gasStep = ensureExecutionStep(plan, stepCodeGasTopUp)
+		gasStep.Description = "Top up native gas from fee wallet"
+		gasStep.Amount = cloneMoney(topUpMoney)
+		gasStep.NetworkFee = cloneMoney(topUpFee)
+		gasStep.SourceWalletRef = feeWalletRef
+		gasStep.DestinationRef = sourceWalletRef
+	}
+
+	fundStep := ensureExecutionStep(plan, stepCodeFundingTransfer)
+	fundStep.Description = "Transfer payout amount to card funding wallet"
+	fundStep.Amount = cloneMoney(amount)
+	fundStep.NetworkFee = cloneMoney(fundingFee)
+	fundStep.SourceWalletRef = sourceWalletRef
+	fundStep.DestinationRef = fundingAddress
+
+	cardStep := ensureExecutionStep(plan, stepCodeCardPayout)
+	cardStep.Description = "Submit card payout"
+	cardStep.Amount = cloneMoney(payoutAmount)
+	if card := intent.Destination.Card; card != nil {
+		if masked := strings.TrimSpace(card.MaskedPan); masked != "" {
+			cardStep.DestinationRef = masked
+		}
+	}
+
+	if feeRequired {
+		step := ensureExecutionStep(plan, stepCodeFeeTransfer)
+		step.Description = "Transfer fee to fee wallet"
+		step.Amount = cloneMoney(feeMoney)
+		step.NetworkFee = cloneMoney(feeTransferFee)
+		step.SourceWalletRef = sourceWalletRef
+		step.DestinationRef = feeWalletRef
+	}
+
+	updateExecutionPlanTotalNetworkFee(plan)
+
 	exec := payment.Execution
 	if exec == nil {
 		exec = &model.ExecutionRefs{}
 	}
 
+	if topUpMoney != nil && topUpPositive {
+		ensureResp, gasErr := s.deps.gateway.client.EnsureGasTopUp(ctx, &chainv1.EnsureGasTopUpRequest{
+			IdempotencyKey:    payment.IdempotencyKey + ":card:gas",
+			OrganizationRef:   payment.OrganizationRef.Hex(),
+			SourceWalletRef:   feeWalletRef,
+			TargetWalletRef:   sourceWalletRef,
+			EstimatedTotalFee: estimatedTotalFee,
+			Metadata:          cloneMetadata(payment.Metadata),
+			ClientReference:   payment.PaymentRef,
+		})
+		if gasErr != nil {
+			s.logger.Warn("card gas top-up transfer failed", zap.Error(gasErr), zap.String("payment_ref", payment.PaymentRef))
+			return gasErr
+		}
+		if gasStep != nil {
+			actual := (*moneyv1.Money)(nil)
+			if ensureResp != nil {
+				actual = ensureResp.GetTopupAmount()
+				if transfer := ensureResp.GetTransfer(); transfer != nil {
+					gasStep.TransferRef = strings.TrimSpace(transfer.GetTransferRef())
+				}
+			}
+			actualPositive := false
+			if actual != nil && strings.TrimSpace(actual.GetAmount()) != "" {
+				actualDec, err := decimalFromMoney(actual)
+				if err != nil {
+					return err
+				}
+				actualPositive = actualDec.IsPositive()
+			}
+			if actual != nil && actualPositive {
+				gasStep.Amount = cloneMoney(actual)
+				if strings.TrimSpace(actual.GetCurrency()) == "" {
+					return merrors.InvalidArgument("card funding: gas top-up currency is required")
+				}
+				topUpDest := &chainv1.TransferDestination{
+					Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: sourceWalletRef},
+				}
+				topUpFee, err = s.estimateTransferNetworkFee(ctx, feeWalletRef, topUpDest, actual)
+				if err != nil {
+					return err
+				}
+				gasStep.NetworkFee = cloneMoney(topUpFee)
+			} else {
+				gasStep.Amount = nil
+				gasStep.NetworkFee = nil
+			}
+		}
+		if gasStep != nil {
+			s.logger.Info("card gas top-up transfer submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", gasStep.TransferRef))
+		}
+		updateExecutionPlanTotalNetworkFee(plan)
+	}
+
 	// Transfer payout amount to funding wallet.
 	fundReq := &chainv1.SubmitTransferRequest{
 		IdempotencyKey:  payment.IdempotencyKey + ":card:fund",
 		OrganizationRef: payment.OrganizationRef.Hex(),
-		SourceWalletRef: strings.TrimSpace(source.ManagedWalletRef),
+		SourceWalletRef: sourceWalletRef,
 		Destination: &chainv1.TransferDestination{
-			Destination: &chainv1.TransferDestination_ExternalAddress{ExternalAddress: strings.TrimSpace(route.FundingAddress)},
+			Destination: &chainv1.TransferDestination_ExternalAddress{ExternalAddress: fundingAddress},
 		},
 		Amount:          amount,
 		Metadata:        cloneMetadata(payment.Metadata),
@@ -84,42 +282,10 @@ func (s *Service) submitCardFundingTransfers(ctx context.Context, payment *model
 	}
 	if fundResp != nil && fundResp.GetTransfer() != nil {
 		exec.ChainTransferRef = strings.TrimSpace(fundResp.GetTransfer().GetTransferRef())
+		fundStep.TransferRef = exec.ChainTransferRef
 	}
 	s.logger.Info("card funding transfer submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", exec.ChainTransferRef))
 
-	feeMoney := quote.GetExpectedFeeTotal()
-	if feeMoney != nil && strings.TrimSpace(feeMoney.GetAmount()) != "" {
-		if strings.TrimSpace(route.FeeAddress) == "" {
-			return merrors.InvalidArgument("card funding: fee address is required when fee exists")
-		}
-		feeDecimal, err := decimalFromMoney(feeMoney)
-		if err != nil {
-			return err
-		}
-		if feeDecimal.IsPositive() {
-			feeReq := &chainv1.SubmitTransferRequest{
-				IdempotencyKey:  payment.IdempotencyKey + ":card:fee",
-				OrganizationRef: payment.OrganizationRef.Hex(),
-				SourceWalletRef: strings.TrimSpace(source.ManagedWalletRef),
-				Destination: &chainv1.TransferDestination{
-					Destination: &chainv1.TransferDestination_ExternalAddress{ExternalAddress: strings.TrimSpace(route.FeeAddress)},
-				},
-				Amount:          feeMoney,
-				Metadata:        cloneMetadata(payment.Metadata),
-				ClientReference: payment.PaymentRef,
-			}
-			feeResp, feeErr := s.deps.gateway.client.SubmitTransfer(ctx, feeReq)
-			if feeErr != nil {
-				s.logger.Warn("card fee transfer failed", zap.Error(feeErr), zap.String("payment_ref", payment.PaymentRef))
-				return feeErr
-			}
-			if feeResp != nil && feeResp.GetTransfer() != nil {
-				exec.FeeTransferRef = strings.TrimSpace(feeResp.GetTransfer().GetTransferRef())
-			}
-			s.logger.Info("card fee transfer submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", exec.FeeTransferRef))
-		}
-	}
-
 	payment.Execution = exec
 	return nil
 }
@@ -133,9 +299,9 @@ func (s *Service) submitCardPayout(ctx context.Context, payment *model.Payment)
 	if card == nil {
 		return merrors.InvalidArgument("card payout: card endpoint is required")
 	}
-	amount := cloneMoney(intent.Amount)
-	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
-		return merrors.InvalidArgument("card payout: amount is required")
+	amount, err := cardPayoutAmount(payment)
+	if err != nil {
+		return err
 	}
 	amtDec, err := decimalFromMoney(amount)
 	if err != nil {
@@ -193,13 +359,92 @@ func (s *Service) submitCardPayout(ctx context.Context, payment *model.Payment)
 		return merrors.Internal("card payout: missing payout state")
 	}
 	recordCardPayoutState(payment, state)
-	if payment.Execution == nil {
-		payment.Execution = &model.ExecutionRefs{}
+	exec := payment.Execution
+	if exec == nil {
+		exec = &model.ExecutionRefs{}
 	}
-	if payment.Execution.CardPayoutRef == "" {
-		payment.Execution.CardPayoutRef = strings.TrimSpace(state.GetPayoutId())
+	if exec.CardPayoutRef == "" {
+		exec.CardPayoutRef = strings.TrimSpace(state.GetPayoutId())
 	}
-	s.logger.Info("card payout submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("payout_id", payment.Execution.CardPayoutRef))
+	payment.Execution = exec
+
+	plan := ensureExecutionPlan(payment)
+	if plan != nil {
+		step := ensureExecutionStep(plan, stepCodeCardPayout)
+		step.Description = "Submit card payout"
+		step.Amount = cloneMoney(amount)
+		if masked := strings.TrimSpace(card.MaskedPan); masked != "" {
+			step.DestinationRef = masked
+		}
+		if exec.CardPayoutRef != "" {
+			step.TransferRef = exec.CardPayoutRef
+		}
+		updateExecutionPlanTotalNetworkFee(plan)
+	}
+
+	feeMoney := (*moneyv1.Money)(nil)
+	if payment.LastQuote != nil {
+		feeMoney = payment.LastQuote.ExpectedFeeTotal
+	}
+	if feeMoney != nil && strings.TrimSpace(feeMoney.GetAmount()) != "" {
+		if strings.TrimSpace(feeMoney.GetCurrency()) == "" {
+			return merrors.InvalidArgument("card payout: fee currency is required")
+		}
+		feeDecimal, err := decimalFromMoney(feeMoney)
+		if err != nil {
+			return err
+		}
+		if feeDecimal.IsPositive() {
+			if !s.deps.gateway.available() {
+				s.logger.Warn("card fee aborted: chain gateway unavailable")
+				return merrors.InvalidArgument("card payout: chain gateway unavailable")
+			}
+			sourceWallet := intent.Source.ManagedWallet
+			if sourceWallet == nil || strings.TrimSpace(sourceWallet.ManagedWalletRef) == "" {
+				return merrors.InvalidArgument("card payout: source managed wallet is required")
+			}
+			route, err := s.cardRoute(defaultCardGateway)
+			if err != nil {
+				return err
+			}
+			feeWalletRef := strings.TrimSpace(route.FeeWalletRef)
+			if feeWalletRef == "" {
+				return merrors.InvalidArgument("card payout: fee wallet ref is required when fee exists")
+			}
+			feeReq := &chainv1.SubmitTransferRequest{
+				IdempotencyKey:  payment.IdempotencyKey + ":card:fee",
+				OrganizationRef: payment.OrganizationRef.Hex(),
+				SourceWalletRef: strings.TrimSpace(sourceWallet.ManagedWalletRef),
+				Destination: &chainv1.TransferDestination{
+					Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: feeWalletRef},
+				},
+				Amount:          feeMoney,
+				Metadata:        cloneMetadata(payment.Metadata),
+				ClientReference: payment.PaymentRef,
+			}
+			feeResp, feeErr := s.deps.gateway.client.SubmitTransfer(ctx, feeReq)
+			if feeErr != nil {
+				s.logger.Warn("card fee transfer failed", zap.Error(feeErr), zap.String("payment_ref", payment.PaymentRef))
+				return feeErr
+			}
+			if feeResp != nil && feeResp.GetTransfer() != nil {
+				exec.FeeTransferRef = strings.TrimSpace(feeResp.GetTransfer().GetTransferRef())
+			}
+			s.logger.Info("card fee transfer submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", exec.FeeTransferRef))
+
+			if plan != nil {
+				step := ensureExecutionStep(plan, stepCodeFeeTransfer)
+				step.Description = "Transfer fee to fee wallet"
+				step.Amount = cloneMoney(feeMoney)
+				step.SourceWalletRef = strings.TrimSpace(sourceWallet.ManagedWalletRef)
+				step.DestinationRef = feeWalletRef
+				step.TransferRef = exec.FeeTransferRef
+				updateExecutionPlanTotalNetworkFee(plan)
+			}
+		}
+	}
+
+	s.logger.Info("card payout submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("payout_id", exec.CardPayoutRef))
 
 	return nil
 }
@@ -250,3 +495,147 @@ func applyCardPayoutUpdate(payment *model.Payment, payout *mntxv1.CardPayoutStat
 		// leave as-is for pending/unspecified
 	}
 }
+
+func cardPayoutAmount(payment *model.Payment) (*moneyv1.Money, error) {
+	if payment == nil {
+		return nil, merrors.InvalidArgument("payment is required")
+	}
+	amount := cloneMoney(payment.Intent.Amount)
+	if payment.LastQuote != nil {
+		settlement := payment.LastQuote.ExpectedSettlementAmount
+		if settlement != nil && strings.TrimSpace(settlement.GetAmount()) != "" && strings.TrimSpace(settlement.GetCurrency()) != "" {
+			amount = cloneMoney(settlement)
+		}
+	}
+	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("card payout: amount is required")
+	}
+	return amount, nil
+}
+
+func (s *Service) estimateTransferNetworkFee(ctx context.Context, sourceWalletRef string, destination *chainv1.TransferDestination, amount *moneyv1.Money) (*moneyv1.Money, error) {
+	if !s.deps.gateway.available() {
+		return nil, merrors.InvalidArgument("chain gateway unavailable")
+	}
+	sourceWalletRef = strings.TrimSpace(sourceWalletRef)
+	if sourceWalletRef == "" {
+		return nil, merrors.InvalidArgument("source wallet ref is required")
+	}
+	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("amount is required")
+	}
+
+	resp, err := s.deps.gateway.client.EstimateTransferFee(ctx, &chainv1.EstimateTransferFeeRequest{
+		SourceWalletRef: sourceWalletRef,
+		Destination:     destination,
+		Amount:          cloneMoney(amount),
+	})
+	if err != nil {
+		s.logger.Warn("chain gateway fee estimation failed", zap.Error(err), zap.String("source_wallet_ref", sourceWalletRef))
+		return nil, merrors.Internal("chain_gateway_fee_estimation_failed")
+	}
+	if resp == nil {
+		s.logger.Warn("chain gateway fee estimation returned empty response", zap.String("source_wallet_ref", sourceWalletRef))
+		return nil, merrors.Internal("chain_gateway_fee_estimation_failed")
+	}
+	fee := resp.GetNetworkFee()
+	if fee == nil || strings.TrimSpace(fee.GetAmount()) == "" || strings.TrimSpace(fee.GetCurrency()) == "" {
+		s.logger.Warn("chain gateway fee estimation missing network fee", zap.String("source_wallet_ref", sourceWalletRef))
+		return nil, merrors.Internal("chain_gateway_fee_estimation_failed")
+	}
+	return cloneMoney(fee), nil
+}
+
+func sumNetworkFees(fees ...*moneyv1.Money) (decimal.Decimal, string, error) {
+	total := decimal.Zero
+	currency := ""
+	for _, fee := range fees {
+		if fee == nil {
+			continue
+		}
+		amount := strings.TrimSpace(fee.GetAmount())
+		feeCurrency := strings.TrimSpace(fee.GetCurrency())
+		if amount == "" || feeCurrency == "" {
+			return decimal.Zero, "", merrors.InvalidArgument("network fee is required")
+		}
+		value, err := decimalFromMoney(fee)
+		if err != nil {
+			return decimal.Zero, "", err
+		}
+		if currency == "" {
+			currency = feeCurrency
+		} else if !strings.EqualFold(currency, feeCurrency) {
+			return decimal.Zero, "", merrors.InvalidArgument("network fee currency mismatch")
+		}
+		total = total.Add(value)
+	}
+	return total, currency, nil
+}
+
+func ensureExecutionPlan(payment *model.Payment) *model.ExecutionPlan {
+	if payment == nil {
+		return nil
+	}
+	if payment.ExecutionPlan == nil {
+		payment.ExecutionPlan = &model.ExecutionPlan{}
+	}
+	return payment.ExecutionPlan
+}
+
+func ensureExecutionStep(plan *model.ExecutionPlan, code string) *model.ExecutionStep {
+	if plan == nil {
+		return nil
+	}
+	code = strings.TrimSpace(code)
+	if code == "" {
+		return nil
+	}
+	for _, step := range plan.Steps {
+		if step == nil {
+			continue
+		}
+		if strings.EqualFold(step.Code, code) {
+			if step.Code == "" {
+				step.Code = code
+			}
+			return step
+		}
+	}
+	step := &model.ExecutionStep{Code: code}
+	plan.Steps = append(plan.Steps, step)
+	return step
+}
+
+func updateExecutionPlanTotalNetworkFee(plan *model.ExecutionPlan) {
+	if plan == nil {
+		return
+	}
+	total := decimal.Zero
+	currency := ""
+	hasFee := false
+	for _, step := range plan.Steps {
+		if step == nil || step.NetworkFee == nil {
+			continue
+		}
+		fee := step.NetworkFee
+		if strings.TrimSpace(fee.GetAmount()) == "" || strings.TrimSpace(fee.GetCurrency()) == "" {
+			continue
+		}
+		if currency == "" {
+			currency = strings.TrimSpace(fee.GetCurrency())
+		} else if !strings.EqualFold(currency, fee.GetCurrency()) {
+			continue
+		}
+		value, err := decimalFromMoney(fee)
+		if err != nil {
+			continue
+		}
+		total = total.Add(value)
+		hasFee = true
+	}
+	if !hasFee || currency == "" {
+		plan.TotalNetworkFee = nil
+		return
+	}
+	plan.TotalNetworkFee = makeMoney(currency, total)
+}

api/payments/orchestrator/internal/service/orchestrator/card_payout_test.go

@@ -0,0 +1,407 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	chainclient "github.com/tech/sendico/gateway/chain/client"
+	mntxclient "github.com/tech/sendico/gateway/mntx/client"
+	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	mo "github.com/tech/sendico/pkg/model"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.mongodb.org/mongo-driver/bson/primitive"
+	"go.uber.org/zap"
+)
+
+func TestSubmitCardFundingTransfers_PlansTopUpAndFunding(t *testing.T) {
+	ctx := context.Background()
+
+	const (
+		sourceWalletRef = "wallet-src"
+		feeWalletRef    = "wallet-fee"
+		fundingAddress  = "0xfunding"
+	)
+
+	var estimateCalls []*chainv1.EstimateTransferFeeRequest
+	var computeCalls []*chainv1.ComputeGasTopUpRequest
+	var ensureCalls []*chainv1.EnsureGasTopUpRequest
+	var submitCalls []*chainv1.SubmitTransferRequest
+
+	gateway := &chainclient.Fake{
+		EstimateTransferFeeFn: func(ctx context.Context, req *chainv1.EstimateTransferFeeRequest) (*chainv1.EstimateTransferFeeResponse, error) {
+			estimateCalls = append(estimateCalls, req)
+			dest := req.GetDestination()
+			if req.GetSourceWalletRef() == feeWalletRef {
+				return &chainv1.EstimateTransferFeeResponse{
+					NetworkFee: &moneyv1.Money{Currency: "ETH", Amount: "0.005"},
+				}, nil
+			}
+			if dest != nil && strings.TrimSpace(dest.GetExternalAddress()) != "" {
+				return &chainv1.EstimateTransferFeeResponse{
+					NetworkFee: &moneyv1.Money{Currency: "ETH", Amount: "0.01"},
+				}, nil
+			}
+			return &chainv1.EstimateTransferFeeResponse{
+				NetworkFee: &moneyv1.Money{Currency: "ETH", Amount: "0.02"},
+			}, nil
+		},
+		ComputeGasTopUpFn: func(ctx context.Context, req *chainv1.ComputeGasTopUpRequest) (*chainv1.ComputeGasTopUpResponse, error) {
+			computeCalls = append(computeCalls, req)
+			return &chainv1.ComputeGasTopUpResponse{
+				TopupAmount: &moneyv1.Money{Currency: "ETH", Amount: "0.025"},
+			}, nil
+		},
+		EnsureGasTopUpFn: func(ctx context.Context, req *chainv1.EnsureGasTopUpRequest) (*chainv1.EnsureGasTopUpResponse, error) {
+			ensureCalls = append(ensureCalls, req)
+			return &chainv1.EnsureGasTopUpResponse{
+				TopupAmount: &moneyv1.Money{Currency: "ETH", Amount: "0.025"},
+				Transfer:    &chainv1.Transfer{TransferRef: req.GetIdempotencyKey()},
+			}, nil
+		},
+		SubmitTransferFn: func(ctx context.Context, req *chainv1.SubmitTransferRequest) (*chainv1.SubmitTransferResponse, error) {
+			submitCalls = append(submitCalls, req)
+			return &chainv1.SubmitTransferResponse{
+				Transfer: &chainv1.Transfer{TransferRef: req.GetIdempotencyKey()},
+			}, nil
+		},
+	}
+
+	svc := &Service{
+		logger: zap.NewNop(),
+		deps: serviceDependencies{
+			gateway: gatewayDependency{client: gateway},
+			cardRoutes: map[string]CardGatewayRoute{
+				defaultCardGateway: {
+					FundingAddress: fundingAddress,
+					FeeWalletRef:   feeWalletRef,
+				},
+			},
+		},
+	}
+
+	payment := &model.Payment{
+		PaymentRef:            "pay-1",
+		IdempotencyKey:        "pay-1",
+		OrganizationBoundBase: mo.OrganizationBoundBase{OrganizationRef: primitive.NewObjectID()},
+		Intent: model.PaymentIntent{
+			Kind: model.PaymentKindPayout,
+			Source: model.PaymentEndpoint{
+				Type: model.EndpointTypeManagedWallet,
+				ManagedWallet: &model.ManagedWalletEndpoint{
+					ManagedWalletRef: sourceWalletRef,
+				},
+			},
+			Destination: model.PaymentEndpoint{
+				Type: model.EndpointTypeCard,
+				Card: &model.CardEndpoint{
+					MaskedPan: "4111",
+				},
+			},
+			Amount: &moneyv1.Money{Currency: "USDT", Amount: "5"},
+		},
+	}
+
+	quote := &orchestratorv1.PaymentQuote{
+		ExpectedFeeTotal: &moneyv1.Money{Currency: "USDT", Amount: "0.35"},
+	}
+
+	if err := svc.submitCardFundingTransfers(ctx, payment, quote); err != nil {
+		t.Fatalf("submitCardFundingTransfers error: %v", err)
+	}
+
+	if len(estimateCalls) != 4 {
+		t.Fatalf("expected 4 fee estimates, got %d", len(estimateCalls))
+	}
+	if len(computeCalls) != 1 {
+		t.Fatalf("expected 1 gas top-up compute call, got %d", len(computeCalls))
+	}
+	if len(ensureCalls) != 1 {
+		t.Fatalf("expected 1 gas top-up ensure call, got %d", len(ensureCalls))
+	}
+	if len(submitCalls) != 1 {
+		t.Fatalf("expected 1 transfer submission, got %d", len(submitCalls))
+	}
+
+	computeCall := computeCalls[0]
+	if computeCall.GetWalletRef() != sourceWalletRef {
+		t.Fatalf("gas top-up compute wallet mismatch: %s", computeCall.GetWalletRef())
+	}
+	if computeCall.GetEstimatedTotalFee().GetCurrency() != "ETH" || computeCall.GetEstimatedTotalFee().GetAmount() != "0.03" {
+		t.Fatalf("gas top-up compute fee mismatch: %s %s", computeCall.GetEstimatedTotalFee().GetCurrency(), computeCall.GetEstimatedTotalFee().GetAmount())
+	}
+
+	ensureCall := ensureCalls[0]
+	if ensureCall.GetSourceWalletRef() != feeWalletRef {
+		t.Fatalf("gas top-up source wallet mismatch: %s", ensureCall.GetSourceWalletRef())
+	}
+	if ensureCall.GetTargetWalletRef() != sourceWalletRef {
+		t.Fatalf("gas top-up destination mismatch: %s", ensureCall.GetTargetWalletRef())
+	}
+	if ensureCall.GetEstimatedTotalFee().GetCurrency() != "ETH" || ensureCall.GetEstimatedTotalFee().GetAmount() != "0.03" {
+		t.Fatalf("gas top-up ensure fee mismatch: %s %s", ensureCall.GetEstimatedTotalFee().GetCurrency(), ensureCall.GetEstimatedTotalFee().GetAmount())
+	}
+
+	fundCall := findSubmitCall(t, submitCalls, "pay-1:card:fund")
+	if fundCall.GetDestination().GetExternalAddress() != fundingAddress {
+		t.Fatalf("funding destination mismatch: %s", fundCall.GetDestination().GetExternalAddress())
+	}
+	if fundCall.GetAmount().GetCurrency() != "USDT" || fundCall.GetAmount().GetAmount() != "5" {
+		t.Fatalf("funding amount mismatch: %s %s", fundCall.GetAmount().GetCurrency(), fundCall.GetAmount().GetAmount())
+	}
+
+	if payment.Execution == nil || payment.Execution.ChainTransferRef != "pay-1:card:fund" {
+		t.Fatalf("expected funding transfer ref recorded, got %v", payment.Execution)
+	}
+
+	plan := payment.ExecutionPlan
+	if plan == nil {
+		t.Fatal("expected execution plan to be populated")
+	}
+	gasStep := findExecutionStep(t, plan, stepCodeGasTopUp)
+	if gasStep.Amount.GetAmount() != "0.025" || gasStep.Amount.GetCurrency() != "ETH" {
+		t.Fatalf("gas step amount mismatch: %s %s", gasStep.Amount.GetCurrency(), gasStep.Amount.GetAmount())
+	}
+	if gasStep.NetworkFee.GetAmount() != "0.005" || gasStep.NetworkFee.GetCurrency() != "ETH" {
+		t.Fatalf("gas step fee mismatch: %s %s", gasStep.NetworkFee.GetCurrency(), gasStep.NetworkFee.GetAmount())
+	}
+	if gasStep.TransferRef != "pay-1:card:gas" {
+		t.Fatalf("expected gas step transfer ref to be set, got %s", gasStep.TransferRef)
+	}
+
+	fundStep := findExecutionStep(t, plan, stepCodeFundingTransfer)
+	if fundStep.NetworkFee.GetAmount() != "0.01" || fundStep.NetworkFee.GetCurrency() != "ETH" {
+		t.Fatalf("funding step fee mismatch: %s %s", fundStep.NetworkFee.GetCurrency(), fundStep.NetworkFee.GetAmount())
+	}
+	if fundStep.TransferRef != "pay-1:card:fund" {
+		t.Fatalf("funding step transfer ref mismatch: %s", fundStep.TransferRef)
+	}
+
+	cardStep := findExecutionStep(t, plan, stepCodeCardPayout)
+	if cardStep.Amount.GetAmount() != "5" || cardStep.Amount.GetCurrency() != "USDT" {
+		t.Fatalf("card step amount mismatch: %s %s", cardStep.Amount.GetCurrency(), cardStep.Amount.GetAmount())
+	}
+
+	feeStep := findExecutionStep(t, plan, stepCodeFeeTransfer)
+	if feeStep.Amount.GetAmount() != "0.35" || feeStep.Amount.GetCurrency() != "USDT" {
+		t.Fatalf("fee step amount mismatch: %s %s", feeStep.Amount.GetCurrency(), feeStep.Amount.GetAmount())
+	}
+	if feeStep.NetworkFee.GetAmount() != "0.02" || feeStep.NetworkFee.GetCurrency() != "ETH" {
+		t.Fatalf("fee step network fee mismatch: %s %s", feeStep.NetworkFee.GetCurrency(), feeStep.NetworkFee.GetAmount())
+	}
+	if feeStep.TransferRef != "" {
+		t.Fatalf("expected fee step transfer ref to be empty before payout, got %s", feeStep.TransferRef)
+	}
+
+	if plan.TotalNetworkFee == nil || plan.TotalNetworkFee.GetAmount() != "0.035" || plan.TotalNetworkFee.GetCurrency() != "ETH" {
+		t.Fatalf("total network fee mismatch: %v", plan.TotalNetworkFee)
+	}
+}
+
+func TestSubmitCardPayout_UsesSettlementAmountAndTransfersFee(t *testing.T) {
+	ctx := context.Background()
+
+	const (
+		sourceWalletRef = "wallet-src"
+		feeWalletRef    = "wallet-fee"
+	)
+
+	var payoutReq *mntxv1.CardPayoutRequest
+	var submitCalls []*chainv1.SubmitTransferRequest
+
+	gateway := &chainclient.Fake{
+		SubmitTransferFn: func(ctx context.Context, req *chainv1.SubmitTransferRequest) (*chainv1.SubmitTransferResponse, error) {
+			submitCalls = append(submitCalls, req)
+			return &chainv1.SubmitTransferResponse{
+				Transfer: &chainv1.Transfer{TransferRef: "fee-transfer"},
+			}, nil
+		},
+	}
+	mntx := &mntxclient.Fake{
+		CreateCardPayoutFn: func(ctx context.Context, req *mntxv1.CardPayoutRequest) (*mntxv1.CardPayoutResponse, error) {
+			payoutReq = req
+			return &mntxv1.CardPayoutResponse{
+				Payout: &mntxv1.CardPayoutState{
+					PayoutId: "payout-1",
+					Status:   mntxv1.PayoutStatus_PAYOUT_STATUS_PENDING,
+				},
+			}, nil
+		},
+	}
+
+	svc := &Service{
+		logger: zap.NewNop(),
+		deps: serviceDependencies{
+			gateway: gatewayDependency{client: gateway},
+			mntx:    mntxDependency{client: mntx},
+			cardRoutes: map[string]CardGatewayRoute{
+				defaultCardGateway: {
+					FundingAddress: "0xfunding",
+					FeeWalletRef:   feeWalletRef,
+				},
+			},
+		},
+	}
+
+	payment := &model.Payment{
+		PaymentRef:            "pay-2",
+		IdempotencyKey:        "pay-2",
+		OrganizationBoundBase: mo.OrganizationBoundBase{OrganizationRef: primitive.NewObjectID()},
+		Intent: model.PaymentIntent{
+			Kind: model.PaymentKindPayout,
+			Source: model.PaymentEndpoint{
+				Type: model.EndpointTypeManagedWallet,
+				ManagedWallet: &model.ManagedWalletEndpoint{
+					ManagedWalletRef: sourceWalletRef,
+				},
+			},
+			Destination: model.PaymentEndpoint{
+				Type: model.EndpointTypeCard,
+				Card: &model.CardEndpoint{
+					Pan:        "5536913762657597",
+					Cardholder: "Stephan",
+				},
+			},
+			Amount: &moneyv1.Money{Currency: "USDT", Amount: "5"},
+		},
+		LastQuote: &model.PaymentQuoteSnapshot{
+			ExpectedSettlementAmount: &moneyv1.Money{Currency: "RUB", Amount: "392.30"},
+			ExpectedFeeTotal:         &moneyv1.Money{Currency: "USDT", Amount: "0.35"},
+		},
+	}
+
+	if err := svc.submitCardPayout(ctx, payment); err != nil {
+		t.Fatalf("submitCardPayout error: %v", err)
+	}
+
+	if payoutReq == nil {
+		t.Fatal("expected card payout request to be sent")
+	}
+	if payoutReq.GetCurrency() != "RUB" || payoutReq.GetAmountMinor() != 39230 {
+		t.Fatalf("payout request amount mismatch: %s %d", payoutReq.GetCurrency(), payoutReq.GetAmountMinor())
+	}
+
+	if payment.Execution == nil || payment.Execution.CardPayoutRef != "payout-1" {
+		t.Fatalf("expected card payout ref recorded, got %v", payment.Execution)
+	}
+	if payment.Execution.FeeTransferRef != "fee-transfer" {
+		t.Fatalf("expected fee transfer ref recorded, got %v", payment.Execution)
+	}
+
+	if len(submitCalls) != 1 {
+		t.Fatalf("expected 1 fee transfer submission, got %d", len(submitCalls))
+	}
+	feeCall := submitCalls[0]
+	if feeCall.GetSourceWalletRef() != sourceWalletRef {
+		t.Fatalf("fee transfer source mismatch: %s", feeCall.GetSourceWalletRef())
+	}
+	if feeCall.GetDestination().GetManagedWalletRef() != feeWalletRef {
+		t.Fatalf("fee transfer destination mismatch: %s", feeCall.GetDestination().GetManagedWalletRef())
+	}
+
+	plan := payment.ExecutionPlan
+	if plan == nil {
+		t.Fatal("expected execution plan to be populated")
+	}
+	cardStep := findExecutionStep(t, plan, stepCodeCardPayout)
+	if cardStep.TransferRef != "payout-1" {
+		t.Fatalf("card step transfer ref mismatch: %s", cardStep.TransferRef)
+	}
+	if cardStep.Amount.GetAmount() != "392.30" || cardStep.Amount.GetCurrency() != "RUB" {
+		t.Fatalf("card step amount mismatch: %s %s", cardStep.Amount.GetCurrency(), cardStep.Amount.GetAmount())
+	}
+
+	feeStep := findExecutionStep(t, plan, stepCodeFeeTransfer)
+	if feeStep.TransferRef != "fee-transfer" {
+		t.Fatalf("fee step transfer ref mismatch: %s", feeStep.TransferRef)
+	}
+	if feeStep.Amount.GetAmount() != "0.35" || feeStep.Amount.GetCurrency() != "USDT" {
+		t.Fatalf("fee step amount mismatch: %s %s", feeStep.Amount.GetCurrency(), feeStep.Amount.GetAmount())
+	}
+}
+
+func TestSubmitCardFundingTransfers_RequiresFeeWalletRef(t *testing.T) {
+	ctx := context.Background()
+
+	gateway := &chainclient.Fake{
+		EstimateTransferFeeFn: func(ctx context.Context, req *chainv1.EstimateTransferFeeRequest) (*chainv1.EstimateTransferFeeResponse, error) {
+			return &chainv1.EstimateTransferFeeResponse{
+				NetworkFee: &moneyv1.Money{Currency: "ETH", Amount: "0.01"},
+			}, nil
+		},
+	}
+
+	svc := &Service{
+		logger: zap.NewNop(),
+		deps: serviceDependencies{
+			gateway: gatewayDependency{client: gateway},
+			cardRoutes: map[string]CardGatewayRoute{
+				defaultCardGateway: {
+					FundingAddress: "0xfunding",
+				},
+			},
+		},
+	}
+
+	payment := &model.Payment{
+		PaymentRef:            "pay-3",
+		IdempotencyKey:        "pay-3",
+		OrganizationBoundBase: mo.OrganizationBoundBase{OrganizationRef: primitive.NewObjectID()},
+		Intent: model.PaymentIntent{
+			Kind: model.PaymentKindPayout,
+			Source: model.PaymentEndpoint{
+				Type: model.EndpointTypeManagedWallet,
+				ManagedWallet: &model.ManagedWalletEndpoint{
+					ManagedWalletRef: "wallet-src",
+				},
+			},
+			Destination: model.PaymentEndpoint{
+				Type: model.EndpointTypeCard,
+				Card: &model.CardEndpoint{
+					MaskedPan: "4111",
+				},
+			},
+			Amount: &moneyv1.Money{Currency: "USDT", Amount: "5"},
+		},
+	}
+
+	quote := &orchestratorv1.PaymentQuote{
+		ExpectedFeeTotal: &moneyv1.Money{Currency: "USDT", Amount: "0.35"},
+	}
+
+	err := svc.submitCardFundingTransfers(ctx, payment, quote)
+	if err == nil {
+		t.Fatal("expected error for missing fee wallet ref")
+	}
+	if !strings.Contains(err.Error(), "fee wallet ref") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func findSubmitCall(t *testing.T, calls []*chainv1.SubmitTransferRequest, idempotencyKey string) *chainv1.SubmitTransferRequest {
+	t.Helper()
+	for _, call := range calls {
+		if call.GetIdempotencyKey() == idempotencyKey {
+			return call
+		}
+	}
+	t.Fatalf("missing submit transfer call for %s", idempotencyKey)
+	return nil
+}
+
+func findExecutionStep(t *testing.T, plan *model.ExecutionPlan, code string) *model.ExecutionStep {
+	t.Helper()
+	if plan == nil {
+		t.Fatal("execution plan is nil")
+	}
+	for _, step := range plan.Steps {
+		if step != nil && strings.EqualFold(step.Code, code) {
+			return step
+		}
+	}
+	t.Fatalf("missing execution step %s", code)
+	return nil
+}

api/payments/orchestrator/internal/service/orchestrator/command_factory.go

@@ -13,7 +13,7 @@ import (
 type paymentEngine interface {
 	EnsureRepository(ctx context.Context) error
 	BuildPaymentQuote(ctx context.Context, orgRef string, req *orchestratorv1.QuotePaymentRequest) (*orchestratorv1.PaymentQuote, time.Time, error)
-	ResolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, error)
+	ResolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, *orchestratorv1.PaymentIntent, error)
 	ExecutePayment(ctx context.Context, store storage.PaymentsStore, payment *model.Payment, quote *orchestratorv1.PaymentQuote) error
 	Repository() storage.Repository
 }
@@ -30,7 +30,7 @@ func (e defaultPaymentEngine) BuildPaymentQuote(ctx context.Context, orgRef stri
 	return e.svc.buildPaymentQuote(ctx, orgRef, req)
 }
 
-func (e defaultPaymentEngine) ResolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, error) {
+func (e defaultPaymentEngine) ResolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, *orchestratorv1.PaymentIntent, error) {
 	return e.svc.resolvePaymentQuote(ctx, in)
 }
 

api/payments/orchestrator/internal/service/orchestrator/convert.go

@@ -125,6 +125,7 @@ func toProtoPayment(src *model.Payment) *orchestratorv1.Payment {
 		FailureReason:  src.FailureReason,
 		LastQuote:      modelQuoteToProto(src.LastQuote),
 		Execution:      protoExecutionFromModel(src.Execution),
+		ExecutionPlan:  protoExecutionPlanFromModel(src.ExecutionPlan),
 		Metadata:       cloneMetadata(src.Metadata),
 	}
 	if src.CardPayout != nil {
@@ -251,6 +252,41 @@ func protoExecutionFromModel(src *model.ExecutionRefs) *orchestratorv1.Execution
 	}
 }
 
+func protoExecutionStepFromModel(src *model.ExecutionStep) *orchestratorv1.ExecutionStep {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.ExecutionStep{
+		Code:            src.Code,
+		Description:     src.Description,
+		Amount:          cloneMoney(src.Amount),
+		NetworkFee:      cloneMoney(src.NetworkFee),
+		SourceWalletRef: src.SourceWalletRef,
+		DestinationRef:  src.DestinationRef,
+		TransferRef:     src.TransferRef,
+		Metadata:        cloneMetadata(src.Metadata),
+	}
+}
+
+func protoExecutionPlanFromModel(src *model.ExecutionPlan) *orchestratorv1.ExecutionPlan {
+	if src == nil {
+		return nil
+	}
+	steps := make([]*orchestratorv1.ExecutionStep, 0, len(src.Steps))
+	for _, step := range src.Steps {
+		if protoStep := protoExecutionStepFromModel(step); protoStep != nil {
+			steps = append(steps, protoStep)
+		}
+	}
+	if len(steps) == 0 {
+		steps = nil
+	}
+	return &orchestratorv1.ExecutionPlan{
+		Steps:           steps,
+		TotalNetworkFee: cloneMoney(src.TotalNetworkFee),
+	}
+}
+
 func modelQuoteToProto(src *model.PaymentQuoteSnapshot) *orchestratorv1.PaymentQuote {
 	if src == nil {
 		return nil

api/payments/orchestrator/internal/service/orchestrator/handlers_commands.go

@@ -12,6 +12,7 @@ import (
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"
 	"github.com/tech/sendico/pkg/mservice"
+	"github.com/tech/sendico/pkg/mutil/mzap"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 	"go.mongodb.org/mongo-driver/bson/primitive"
 	"go.uber.org/zap"
@@ -61,7 +62,13 @@ func (h *quotePaymentCommand) Execute(ctx context.Context, req *orchestratorv1.Q
 		if err := quotesStore.Create(ctx, record); err != nil {
 			return gsresponse.Auto[orchestratorv1.QuotePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
 		}
-		h.logger.Info("stored payment quote", zap.String("quote_ref", quoteRef), zap.String("org_ref", orgID.Hex()))
+		h.logger.Info(
+			"Stored payment quote",
+			zap.String("quote_ref", quoteRef),
+			mzap.ObjRef("org_ref", orgID),
+			zap.String("idempotency_key", strings.TrimSpace(req.GetIdempotencyKey())),
+			zap.String("kind", intent.GetKind().String()),
+		)
 	}
 
 	return gsresponse.Success(&orchestratorv1.QuotePaymentResponse{Quote: quote})
@@ -79,7 +86,7 @@ func (h *quotePaymentsCommand) Execute(ctx context.Context, req *orchestratorv1.
 	if req == nil {
 		return gsresponse.InvalidArgument[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
 	}
-	orgRef, orgID, err := validateMetaAndOrgRef(req.GetMeta())
+	orgID, orgRef, err := validateMetaAndOrgRef(req.GetMeta())
 	if err != nil {
 		return gsresponse.InvalidArgument[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
@@ -101,7 +108,7 @@ func (h *quotePaymentsCommand) Execute(ctx context.Context, req *orchestratorv1.
 			Intent:         intent,
 			PreviewOnly:    req.GetPreviewOnly(),
 		}
-		quote, expiresAt, err := h.engine.BuildPaymentQuote(ctx, orgRef, quoteReq)
+		quote, expiresAt, err := h.engine.BuildPaymentQuote(ctx, orgID, quoteReq)
 		if err != nil {
 			return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
 		}
@@ -132,11 +139,14 @@ func (h *quotePaymentsCommand) Execute(ctx context.Context, req *orchestratorv1.
 			ExpiresAt: expiresAt,
 		}
 		record.SetID(primitive.NewObjectID())
-		record.SetOrganizationRef(orgID)
+		record.SetOrganizationRef(orgRef)
 		if err := quotesStore.Create(ctx, record); err != nil {
 			return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
 		}
-		h.logger.Info("stored payment quotes", zap.String("quote_ref", quoteRef), zap.String("org_ref", orgID.Hex()))
+		h.logger.Info("Stored payment quotes",
+			zap.String("quote_ref", quoteRef), mzap.ObjRef("org_ref", orgRef),
+			zap.String("idempotency_key", baseKey), zap.Int("quote_count", len(quotes)),
+		)
 	}
 
 	return gsresponse.Success(&orchestratorv1.QuotePaymentsResponse{
@@ -158,7 +168,7 @@ func (h *initiatePaymentsCommand) Execute(ctx context.Context, req *orchestrator
 	if req == nil {
 		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
 	}
-	_, orgID, err := validateMetaAndOrgRef(req.GetMeta())
+	_, orgRef, err := validateMetaAndOrgRef(req.GetMeta())
 	if err != nil {
 		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
@@ -175,7 +185,7 @@ func (h *initiatePaymentsCommand) Execute(ctx context.Context, req *orchestrator
 	if err != nil {
 		return gsresponse.Unavailable[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
-	record, err := quotesStore.GetByRef(ctx, orgID, quoteRef)
+	record, err := quotesStore.GetByRef(ctx, orgRef, quoteRef)
 	if err != nil {
 		if errors.Is(err, storage.ErrQuoteNotFound) {
 			return gsresponse.FailedPrecondition[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, "quote_not_found", merrors.InvalidArgument("quote_ref not found or expired"))
@@ -213,14 +223,14 @@ func (h *initiatePaymentsCommand) Execute(ctx context.Context, req *orchestrator
 		quoteProto.QuoteRef = quoteRef
 
 		perKey := perIntentIdempotencyKey(idempotencyKey, i, len(intents))
-		if existing, err := getPaymentByIdempotencyKey(ctx, store, orgID, perKey); err == nil && existing != nil {
+		if existing, err := getPaymentByIdempotencyKey(ctx, store, orgRef, perKey); err == nil && existing != nil {
 			payments = append(payments, toProtoPayment(existing))
 			continue
 		} else if err != nil && !errors.Is(err, storage.ErrPaymentNotFound) {
 			return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
 		}
 
-		entity := newPayment(orgID, intentProto, perKey, req.GetMetadata(), quoteProto)
+		entity := newPayment(orgRef, intentProto, perKey, req.GetMetadata(), quoteProto)
 		if err = store.Create(ctx, entity); err != nil {
 			if errors.Is(err, storage.ErrDuplicatePayment) {
 				return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.DataConflict("payment already exists"))
@@ -235,6 +245,13 @@ func (h *initiatePaymentsCommand) Execute(ctx context.Context, req *orchestrator
 		payments = append(payments, toProtoPayment(entity))
 	}
 
+	h.logger.Info(
+		"Payments initiated",
+		mzap.ObjRef("org_ref", orgRef),
+		zap.String("quote_ref", quoteRef),
+		zap.String("idempotency_key", idempotencyKey),
+		zap.Int("payment_count", len(payments)),
+	)
 	return gsresponse.Success(&orchestratorv1.InitiatePaymentsResponse{Payments: payments})
 }
 
@@ -255,13 +272,31 @@ func (h *initiatePaymentCommand) Execute(ctx context.Context, req *orchestratorv
 		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
 	intent := req.GetIntent()
-	if err := requireNonNilIntent(intent); err != nil {
-		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	quoteRef := strings.TrimSpace(req.GetQuoteRef())
+	hasIntent := intent != nil
+	hasQuote := quoteRef != ""
+	switch {
+	case !hasIntent && !hasQuote:
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("intent or quote_ref is required"))
+	case hasIntent && hasQuote:
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("intent and quote_ref are mutually exclusive"))
+	}
+	if hasIntent {
+		if err := requireNonNilIntent(intent); err != nil {
+			return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
 	}
 	idempotencyKey, err := requireIdempotencyKey(req.GetIdempotencyKey())
 	if err != nil {
 		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
+	h.logger.Debug(
+		"Initiate payment request accepted",
+		zap.String("org_ref", orgID.Hex()),
+		zap.String("idempotency_key", idempotencyKey),
+		zap.String("quote_ref", quoteRef),
+		zap.Bool("has_intent", hasIntent),
+	)
 
 	store, err := ensurePaymentsStore(h.engine.Repository())
 	if err != nil {
@@ -269,18 +304,24 @@ func (h *initiatePaymentCommand) Execute(ctx context.Context, req *orchestratorv
 	}
 
 	if existing, err := getPaymentByIdempotencyKey(ctx, store, orgID, idempotencyKey); err == nil && existing != nil {
-		h.logger.Debug("idempotent payment request reused", zap.String("payment_ref", existing.PaymentRef), zap.String("org_ref", orgID.Hex()))
+		h.logger.Debug(
+			"idempotent payment request reused",
+			zap.String("payment_ref", existing.PaymentRef),
+			zap.String("org_ref", orgID.Hex()),
+			zap.String("idempotency_key", idempotencyKey),
+			zap.String("quote_ref", quoteRef),
+		)
 		return gsresponse.Success(&orchestratorv1.InitiatePaymentResponse{Payment: toProtoPayment(existing)})
 	} else if err != nil && !errors.Is(err, storage.ErrPaymentNotFound) {
 		return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
 
-	quoteSnapshot, err := h.engine.ResolvePaymentQuote(ctx, quoteResolutionInput{
+	quoteSnapshot, resolvedIntent, err := h.engine.ResolvePaymentQuote(ctx, quoteResolutionInput{
 		OrgRef:         orgRef,
 		OrgID:          orgID,
 		Meta:           req.GetMeta(),
 		Intent:         intent,
-		QuoteRef:       req.GetQuoteRef(),
+		QuoteRef:       quoteRef,
 		IdempotencyKey: req.GetIdempotencyKey(),
 	})
 	if err != nil {
@@ -301,8 +342,17 @@ func (h *initiatePaymentCommand) Execute(ctx context.Context, req *orchestratorv
 	if quoteSnapshot == nil {
 		quoteSnapshot = &orchestratorv1.PaymentQuote{}
 	}
+	if err := requireNonNilIntent(resolvedIntent); err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	h.logger.Debug(
+		"Payment quote resolved",
+		zap.String("org_ref", orgID.Hex()),
+		zap.String("quote_ref", quoteRef),
+		zap.Bool("quote_ref_used", quoteRef != ""),
+	)
 
-	entity := newPayment(orgID, intent, idempotencyKey, req.GetMetadata(), quoteSnapshot)
+	entity := newPayment(orgID, resolvedIntent, idempotencyKey, req.GetMetadata(), quoteSnapshot)
 
 	if err = store.Create(ctx, entity); err != nil {
 		if errors.Is(err, storage.ErrDuplicatePayment) {
@@ -315,7 +365,14 @@ func (h *initiatePaymentCommand) Execute(ctx context.Context, req *orchestratorv
 		return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
 
-	h.logger.Info("payment initiated", zap.String("payment_ref", entity.PaymentRef), zap.String("org_ref", orgID.Hex()), zap.String("kind", intent.GetKind().String()))
+	h.logger.Info(
+		"Payment initiated",
+		zap.String("payment_ref", entity.PaymentRef),
+		zap.String("org_ref", orgID.Hex()),
+		zap.String("kind", resolvedIntent.GetKind().String()),
+		zap.String("quote_ref", quoteSnapshot.GetQuoteRef()),
+		zap.String("idempotency_key", idempotencyKey),
+	)
 	return gsresponse.Success(&orchestratorv1.InitiatePaymentResponse{
 		Payment: toProtoPayment(entity),
 	})
@@ -355,7 +412,7 @@ func (h *cancelPaymentCommand) Execute(ctx context.Context, req *orchestratorv1.
 	if err := store.Update(ctx, payment); err != nil {
 		return gsresponse.Auto[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
-	h.logger.Info("payment cancelled", zap.String("payment_ref", payment.PaymentRef), zap.String("org_ref", payment.OrganizationRef.Hex()))
+	h.logger.Info("Payment cancelled", zap.String("payment_ref", payment.PaymentRef), zap.String("org_ref", payment.OrganizationRef.Hex()))
 	return gsresponse.Success(&orchestratorv1.CancelPaymentResponse{Payment: toProtoPayment(payment)})
 }
 
@@ -396,7 +453,7 @@ func (h *initiateConversionCommand) Execute(ctx context.Context, req *orchestrat
 	}
 
 	if existing, err := getPaymentByIdempotencyKey(ctx, store, orgID, idempotencyKey); err == nil && existing != nil {
-		h.logger.Debug("idempotent conversion request reused", zap.String("payment_ref", existing.PaymentRef), zap.String("org_ref", orgID.Hex()))
+		h.logger.Debug("Idempotent conversion request reused", zap.String("payment_ref", existing.PaymentRef), zap.String("org_ref", orgID.Hex()))
 		return gsresponse.Success(&orchestratorv1.InitiateConversionResponse{Conversion: toProtoPayment(existing)})
 	} else if err != nil && !errors.Is(err, storage.ErrPaymentNotFound) {
 		return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
@@ -439,7 +496,7 @@ func (h *initiateConversionCommand) Execute(ctx context.Context, req *orchestrat
 		return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
 	}
 
-	h.logger.Info("conversion initiated", zap.String("payment_ref", entity.PaymentRef), zap.String("org_ref", orgID.Hex()))
+	h.logger.Info("Conversion initiated", zap.String("payment_ref", entity.PaymentRef), zap.String("org_ref", orgID.Hex()))
 	return gsresponse.Success(&orchestratorv1.InitiateConversionResponse{
 		Conversion: toProtoPayment(entity),
 	})

api/payments/orchestrator/internal/service/orchestrator/options.go

@@ -56,10 +56,11 @@ func (m mntxDependency) available() bool {
 	return m.client != nil
 }
 
-// CardGatewayRoute maps a gateway to its funding and fee destinations (addresses).
+// CardGatewayRoute maps a gateway to its funding and fee destinations.
 type CardGatewayRoute struct {
 	FundingAddress string
 	FeeAddress     string
+	FeeWalletRef   string
 }
 
 // WithFeeEngine wires the fee engine client.

api/payments/orchestrator/internal/service/orchestrator/service_helpers.go

@@ -103,33 +103,40 @@ type quoteResolutionError struct {
 
 func (e quoteResolutionError) Error() string { return e.err.Error() }
 
-func (s *Service) resolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, error) {
+func (s *Service) resolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, *orchestratorv1.PaymentIntent, error) {
 	if ref := strings.TrimSpace(in.QuoteRef); ref != "" {
 		quotesStore, err := ensureQuotesStore(s.storage)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 		record, err := quotesStore.GetByRef(ctx, in.OrgID, ref)
 		if err != nil {
 			if errors.Is(err, storage.ErrQuoteNotFound) {
-				return nil, quoteResolutionError{code: "quote_not_found", err: merrors.InvalidArgument("quote_ref not found or expired")}
+				return nil, nil, quoteResolutionError{code: "quote_not_found", err: merrors.InvalidArgument("quote_ref not found or expired")}
 			}
-			return nil, err
+			return nil, nil, err
 		}
 		if !record.ExpiresAt.IsZero() && s.clock.Now().After(record.ExpiresAt) {
-			return nil, quoteResolutionError{code: "quote_expired", err: merrors.InvalidArgument("quote_ref expired")}
+			return nil, nil, quoteResolutionError{code: "quote_expired", err: merrors.InvalidArgument("quote_ref expired")}
 		}
-		if !proto.Equal(protoIntentFromModel(record.Intent), in.Intent) {
-			return nil, quoteResolutionError{code: "quote_intent_mismatch", err: merrors.InvalidArgument("quote_ref does not match intent")}
+		intent, err := recordIntentFromQuote(record)
+		if err != nil {
+			return nil, nil, err
 		}
-		quote := modelQuoteToProto(record.Quote)
-		if quote == nil {
-			return nil, merrors.InvalidArgument("stored quote is empty")
+		if in.Intent != nil && !proto.Equal(intent, in.Intent) {
+			return nil, nil, quoteResolutionError{code: "quote_intent_mismatch", err: merrors.InvalidArgument("quote_ref does not match intent")}
+		}
+		quote, err := recordQuoteFromQuote(record)
+		if err != nil {
+			return nil, nil, err
 		}
 		quote.QuoteRef = ref
-		return quote, nil
+		return quote, intent, nil
 	}
 
+	if in.Intent == nil {
+		return nil, nil, merrors.InvalidArgument("intent is required")
+	}
 	req := &orchestratorv1.QuotePaymentRequest{
 		Meta:           in.Meta,
 		IdempotencyKey: in.IdempotencyKey,
@@ -138,9 +145,41 @@ func (s *Service) resolvePaymentQuote(ctx context.Context, in quoteResolutionInp
 	}
 	quote, _, err := s.buildPaymentQuote(ctx, in.OrgRef, req)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
-	return quote, nil
+	return quote, in.Intent, nil
+}
+
+func recordIntentFromQuote(record *model.PaymentQuoteRecord) (*orchestratorv1.PaymentIntent, error) {
+	if record == nil {
+		return nil, merrors.InvalidArgument("stored quote payload is incomplete")
+	}
+	if len(record.Intents) > 0 {
+		if len(record.Intents) != 1 {
+			return nil, merrors.InvalidArgument("stored quote payload is incomplete")
+		}
+		return protoIntentFromModel(record.Intents[0]), nil
+	}
+	if record.Intent.Amount == nil && (record.Intent.Kind == "" || record.Intent.Kind == model.PaymentKindUnspecified) {
+		return nil, merrors.InvalidArgument("stored quote payload is incomplete")
+	}
+	return protoIntentFromModel(record.Intent), nil
+}
+
+func recordQuoteFromQuote(record *model.PaymentQuoteRecord) (*orchestratorv1.PaymentQuote, error) {
+	if record == nil {
+		return nil, merrors.InvalidArgument("stored quote is empty")
+	}
+	if record.Quote != nil {
+		return modelQuoteToProto(record.Quote), nil
+	}
+	if len(record.Quotes) > 0 {
+		if len(record.Quotes) != 1 {
+			return nil, merrors.InvalidArgument("stored quote payload is incomplete")
+		}
+		return modelQuoteToProto(record.Quotes[0]), nil
+	}
+	return nil, merrors.InvalidArgument("stored quote is empty")
 }
 
 func newPayment(orgID primitive.ObjectID, intent *orchestratorv1.PaymentIntent, idempotencyKey string, metadata map[string]string, quote *orchestratorv1.PaymentQuote) *model.Payment {

api/payments/orchestrator/internal/service/orchestrator/service_helpers_test.go

@@ -73,7 +73,7 @@ func TestResolvePaymentQuote_NotFound(t *testing.T) {
 		storage: stubRepo{quotes: &helperQuotesStore{}},
 		clock:   clockpkg.NewSystem(),
 	}
-	_, err := svc.resolvePaymentQuote(context.Background(), quoteResolutionInput{
+	_, _, err := svc.resolvePaymentQuote(context.Background(), quoteResolutionInput{
 		OrgRef:   org.Hex(),
 		OrgID:    org,
 		Meta:     &orchestratorv1.RequestMeta{OrganizationRef: org.Hex()},
@@ -98,7 +98,7 @@ func TestResolvePaymentQuote_Expired(t *testing.T) {
 		storage: stubRepo{quotes: &helperQuotesStore{records: map[string]*model.PaymentQuoteRecord{"q1": record}}},
 		clock:   clockpkg.NewSystem(),
 	}
-	_, err := svc.resolvePaymentQuote(context.Background(), quoteResolutionInput{
+	_, _, err := svc.resolvePaymentQuote(context.Background(), quoteResolutionInput{
 		OrgRef:   org.Hex(),
 		OrgID:    org,
 		Meta:     &orchestratorv1.RequestMeta{OrganizationRef: org.Hex()},
@@ -110,6 +110,35 @@ func TestResolvePaymentQuote_Expired(t *testing.T) {
 	}
 }
 
+func TestResolvePaymentQuote_QuoteRefUsesStoredIntent(t *testing.T) {
+	org := primitive.NewObjectID()
+	intent := &orchestratorv1.PaymentIntent{Amount: &moneyv1.Money{Currency: "USD", Amount: "1"}}
+	record := &model.PaymentQuoteRecord{
+		QuoteRef: "q1",
+		Intent:   intentFromProto(intent),
+		Quote:    &model.PaymentQuoteSnapshot{},
+	}
+	svc := &Service{
+		storage: stubRepo{quotes: &helperQuotesStore{records: map[string]*model.PaymentQuoteRecord{"q1": record}}},
+		clock:   clockpkg.NewSystem(),
+	}
+	quote, resolvedIntent, err := svc.resolvePaymentQuote(context.Background(), quoteResolutionInput{
+		OrgRef:   org.Hex(),
+		OrgID:    org,
+		Meta:     &orchestratorv1.RequestMeta{OrganizationRef: org.Hex()},
+		QuoteRef: "q1",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if quote == nil || quote.GetQuoteRef() != "q1" {
+		t.Fatalf("expected quote_ref q1, got %#v", quote)
+	}
+	if resolvedIntent == nil || resolvedIntent.GetAmount().GetAmount() != "1" {
+		t.Fatalf("expected resolved intent with amount, got %#v", resolvedIntent)
+	}
+}
+
 func TestInitiatePaymentIdempotency(t *testing.T) {
 	logger := mloggerfactory.NewLogger(false)
 	org := primitive.NewObjectID()
@@ -140,6 +169,42 @@ func TestInitiatePaymentIdempotency(t *testing.T) {
 	}
 }
 
+func TestInitiatePaymentByQuoteRef(t *testing.T) {
+	logger := mloggerfactory.NewLogger(false)
+	org := primitive.NewObjectID()
+	store := newHelperPaymentStore()
+	intent := &orchestratorv1.PaymentIntent{Amount: &moneyv1.Money{Currency: "USD", Amount: "1"}}
+	record := &model.PaymentQuoteRecord{
+		QuoteRef: "q1",
+		Intent:   intentFromProto(intent),
+		Quote:    &model.PaymentQuoteSnapshot{},
+	}
+	svc := NewService(logger, stubRepo{
+		payments: store,
+		quotes:   &helperQuotesStore{records: map[string]*model.PaymentQuoteRecord{"q1": record}},
+	}, WithClock(clockpkg.NewSystem()))
+	svc.ensureHandlers()
+
+	req := &orchestratorv1.InitiatePaymentRequest{
+		Meta:           &orchestratorv1.RequestMeta{OrganizationRef: org.Hex()},
+		QuoteRef:       "q1",
+		IdempotencyKey: "k1",
+	}
+	resp, err := svc.h.commands.InitiatePayment().Execute(context.Background(), req)(context.Background())
+	if err != nil {
+		t.Fatalf("initiate by quote_ref failed: %v", err)
+	}
+	if resp == nil || resp.GetPayment() == nil {
+		t.Fatalf("expected payment response")
+	}
+	if resp.GetPayment().GetIntent().GetAmount().GetAmount() != "1" {
+		t.Fatalf("expected intent amount to be resolved from quote")
+	}
+	if resp.GetPayment().GetLastQuote().GetQuoteRef() != "q1" {
+		t.Fatalf("expected last quote_ref to be set from stored quote")
+	}
+}
+
 // --- test doubles ---
 
 type stubRepo struct {

api/payments/orchestrator/storage/model/payment.go

@@ -158,6 +158,24 @@ type ExecutionRefs struct {
 	FeeTransferRef   string `bson:"feeTransferRef,omitempty" json:"feeTransferRef,omitempty"`
 }
 
+// ExecutionStep describes a planned or executed payment step for reporting.
+type ExecutionStep struct {
+	Code            string            `bson:"code,omitempty" json:"code,omitempty"`
+	Description     string            `bson:"description,omitempty" json:"description,omitempty"`
+	Amount          *moneyv1.Money    `bson:"amount,omitempty" json:"amount,omitempty"`
+	NetworkFee      *moneyv1.Money    `bson:"networkFee,omitempty" json:"networkFee,omitempty"`
+	SourceWalletRef string            `bson:"sourceWalletRef,omitempty" json:"sourceWalletRef,omitempty"`
+	DestinationRef  string            `bson:"destinationRef,omitempty" json:"destinationRef,omitempty"`
+	TransferRef     string            `bson:"transferRef,omitempty" json:"transferRef,omitempty"`
+	Metadata        map[string]string `bson:"metadata,omitempty" json:"metadata,omitempty"`
+}
+
+// ExecutionPlan captures the ordered list of steps to execute a payment.
+type ExecutionPlan struct {
+	Steps            []*ExecutionStep `bson:"steps,omitempty" json:"steps,omitempty"`
+	TotalNetworkFee  *moneyv1.Money   `bson:"totalNetworkFee,omitempty" json:"totalNetworkFee,omitempty"`
+}
+
 // Payment persists orchestrated payment lifecycle.
 type Payment struct {
 	storable.Base               `bson:",inline" json:",inline"`
@@ -171,6 +189,7 @@ type Payment struct {
 	FailureReason  string                `bson:"failureReason,omitempty" json:"failureReason,omitempty"`
 	LastQuote      *PaymentQuoteSnapshot `bson:"lastQuote,omitempty" json:"lastQuote,omitempty"`
 	Execution      *ExecutionRefs        `bson:"execution,omitempty" json:"execution,omitempty"`
+	ExecutionPlan  *ExecutionPlan        `bson:"executionPlan,omitempty" json:"executionPlan,omitempty"`
 	Metadata       map[string]string     `bson:"metadata,omitempty" json:"metadata,omitempty"`
 	CardPayout     *CardPayout           `bson:"cardPayout,omitempty" json:"cardPayout,omitempty"`
 }
@@ -218,6 +237,23 @@ func (p *Payment) Normalize() {
 		p.Execution.FXEntryRef = strings.TrimSpace(p.Execution.FXEntryRef)
 		p.Execution.ChainTransferRef = strings.TrimSpace(p.Execution.ChainTransferRef)
 	}
+	if p.ExecutionPlan != nil {
+		for _, step := range p.ExecutionPlan.Steps {
+			if step == nil {
+				continue
+			}
+			step.Code = strings.TrimSpace(step.Code)
+			step.Description = strings.TrimSpace(step.Description)
+			step.SourceWalletRef = strings.TrimSpace(step.SourceWalletRef)
+			step.DestinationRef = strings.TrimSpace(step.DestinationRef)
+			step.TransferRef = strings.TrimSpace(step.TransferRef)
+			if step.Metadata != nil {
+				for k, v := range step.Metadata {
+					step.Metadata[k] = strings.TrimSpace(v)
+				}
+			}
+		}
+	}
 }
 
 func normalizeEndpoint(ep *PaymentEndpoint) {

api/proto/gateway/chain/v1/chain.proto

@@ -100,6 +100,7 @@ message WalletBalance {
   common.money.v1.Money pending_inbound = 2;
   common.money.v1.Money pending_outbound = 3;
   google.protobuf.Timestamp calculated_at = 4;
+  common.money.v1.Money native_available = 5;
 }
 
 message GetWalletBalanceRequest {
@@ -188,6 +189,32 @@ message EstimateTransferFeeResponse {
   string estimation_context = 2;
 }
 
+message ComputeGasTopUpRequest {
+  string wallet_ref = 1;
+  common.money.v1.Money estimated_total_fee = 2;
+}
+
+message ComputeGasTopUpResponse {
+  common.money.v1.Money topup_amount = 1;
+  bool cap_hit = 2;
+}
+
+message EnsureGasTopUpRequest {
+  string idempotency_key = 1;
+  string organization_ref = 2;
+  string source_wallet_ref = 3;
+  string target_wallet_ref = 4;
+  common.money.v1.Money estimated_total_fee = 5;
+  map<string, string> metadata = 6;
+  string client_reference = 7;
+}
+
+message EnsureGasTopUpResponse {
+  common.money.v1.Money topup_amount = 1;
+  bool cap_hit = 2;
+  Transfer transfer = 3;
+}
+
 message WalletDepositObservedEvent {
   string deposit_ref = 1;
   string wallet_ref = 2;
@@ -217,4 +244,6 @@ service ChainGatewayService {
   rpc ListTransfers(ListTransfersRequest) returns (ListTransfersResponse);
 
   rpc EstimateTransferFee(EstimateTransferFeeRequest) returns (EstimateTransferFeeResponse);
+  rpc ComputeGasTopUp(ComputeGasTopUpRequest) returns (ComputeGasTopUpResponse);
+  rpc EnsureGasTopUp(EnsureGasTopUpRequest) returns (EnsureGasTopUpResponse);
 }

api/proto/payments/orchestrator/v1/orchestrator.proto

@@ -141,6 +141,22 @@ message ExecutionRefs {
   string fee_transfer_ref = 6;
 }
 
+message ExecutionStep {
+  string code = 1;
+  string description = 2;
+  common.money.v1.Money amount = 3;
+  common.money.v1.Money network_fee = 4;
+  string source_wallet_ref = 5;
+  string destination_ref = 6;
+  string transfer_ref = 7;
+  map<string, string> metadata = 8;
+}
+
+message ExecutionPlan {
+  repeated ExecutionStep steps = 1;
+  common.money.v1.Money total_network_fee = 2;
+}
+
 // Card payout gateway tracking info.
 message CardPayout {
   string payout_ref = 1;
@@ -166,6 +182,7 @@ message Payment {
   google.protobuf.Timestamp created_at = 10;
   google.protobuf.Timestamp updated_at = 11;
   CardPayout card_payout = 12;
+  ExecutionPlan execution_plan = 13;
 }
 
 message QuotePaymentRequest {

api/server/interface/api/sresponse/payment.go

@@ -7,7 +7,6 @@ import (
 	"github.com/tech/sendico/pkg/mlogger"
 	"github.com/tech/sendico/pkg/model"
 	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
-	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
 	oraclev1 "github.com/tech/sendico/pkg/proto/oracle/v1"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )
@@ -20,11 +19,6 @@ type FeeLine struct {
 	Meta             map[string]string `json:"meta,omitempty"`
 }
 
-type NetworkFee struct {
-	NetworkFee        *model.Money `json:"networkFee,omitempty"`
-	EstimationContext string       `json:"estimationContext,omitempty"`
-}
-
 type FxQuote struct {
 	QuoteRef        string       `json:"quoteRef,omitempty"`
 	BaseCurrency    string       `json:"baseCurrency,omitempty"`
@@ -45,7 +39,6 @@ type PaymentQuote struct {
 	ExpectedSettlementAmount *model.Money `json:"expectedSettlementAmount,omitempty"`
 	ExpectedFeeTotal         *model.Money `json:"expectedFeeTotal,omitempty"`
 	FeeLines                 []FeeLine    `json:"feeLines,omitempty"`
-	NetworkFee               *NetworkFee  `json:"networkFee,omitempty"`
 	FxQuote                  *FxQuote     `json:"fxQuote,omitempty"`
 }
 
@@ -53,7 +46,6 @@ type PaymentQuoteAggregate struct {
 	DebitAmounts              []*model.Money `json:"debitAmounts,omitempty"`
 	ExpectedSettlementAmounts []*model.Money `json:"expectedSettlementAmounts,omitempty"`
 	ExpectedFeeTotals         []*model.Money `json:"expectedFeeTotals,omitempty"`
-	NetworkFeeTotals          []*model.Money `json:"networkFeeTotals,omitempty"`
 }
 
 type PaymentQuotes struct {
@@ -146,16 +138,6 @@ func toFeeLines(lines []*feesv1.DerivedPostingLine) []FeeLine {
 	return result
 }
 
-func toNetworkFee(n *chainv1.EstimateTransferFeeResponse) *NetworkFee {
-	if n == nil {
-		return nil
-	}
-	return &NetworkFee{
-		NetworkFee:        toMoney(n.GetNetworkFee()),
-		EstimationContext: n.GetEstimationContext(),
-	}
-}
-
 func toFxQuote(q *oraclev1.Quote) *FxQuote {
 	if q == nil {
 		return nil
@@ -192,7 +174,6 @@ func toPaymentQuote(q *orchestratorv1.PaymentQuote) *PaymentQuote {
 		ExpectedSettlementAmount: toMoney(q.GetExpectedSettlementAmount()),
 		ExpectedFeeTotal:         toMoney(q.GetExpectedFeeTotal()),
 		FeeLines:                 toFeeLines(q.GetFeeLines()),
-		NetworkFee:               toNetworkFee(q.GetNetworkFee()),
 		FxQuote:                  toFxQuote(q.GetFxQuote()),
 	}
 }
@@ -205,7 +186,6 @@ func toPaymentQuoteAggregate(q *orchestratorv1.PaymentQuoteAggregate) *PaymentQu
 		DebitAmounts:              toMoneyList(q.GetDebitAmounts()),
 		ExpectedSettlementAmounts: toMoneyList(q.GetExpectedSettlementAmounts()),
 		ExpectedFeeTotals:         toMoneyList(q.GetExpectedFeeTotals()),
-		NetworkFeeTotals:          toMoneyList(q.GetNetworkFeeTotals()),
 	}
 }
 

api/server/internal/server/paymentapiimp/pay.go

@@ -8,6 +8,7 @@ import (
 	"github.com/tech/sendico/pkg/api/http/response"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model"
+	"github.com/tech/sendico/pkg/mutil/mzap"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 	"github.com/tech/sendico/server/interface/api/srequest"
 	"github.com/tech/sendico/server/interface/api/sresponse"
@@ -20,7 +21,7 @@ import (
 func (a *PaymentAPI) initiatePayment(r *http.Request, account *model.Account, token *sresponse.TokenData, expectQuote bool) http.HandlerFunc {
 	orgRef, err := a.oph.GetRef(r)
 	if err != nil {
-		a.logger.Warn("Failed to parse organization reference for payment initiation", zap.Error(err), zap.String(a.oph.Name(), a.oph.GetID(r)))
+		a.logger.Warn("Failed to parse organization reference for payment initiation", zap.Error(err), mutil.PLog(a.oph, r))
 		return response.BadReference(a.logger, a.Name(), a.oph.Name(), a.oph.GetID(r), err)
 	}
 
@@ -76,7 +77,7 @@ func (a *PaymentAPI) initiatePayment(r *http.Request, account *model.Account, to
 
 	resp, err := a.client.InitiatePayment(ctx, req)
 	if err != nil {
-		a.logger.Warn("Failed to initiate payment", zap.Error(err), zap.String("organization_ref", orgRef.Hex()))
+		a.logger.Warn("Failed to initiate payment", zap.Error(err), mzap.ObjRef("organization_ref", orgRef))
 		return response.Auto(a.logger, a.Name(), err)
 	}
 

frontend/pshared/lib/api/responses/payment/payment.dart

@@ -0,0 +1,20 @@
+import 'package:json_annotation/json_annotation.dart';
+
+import 'package:pshared/api/responses/base.dart';
+import 'package:pshared/api/responses/token.dart';
+import 'package:pshared/data/dto/payment/payment.dart';
+
+part 'payment.g.dart';
+
+
+@JsonSerializable(explicitToJson: true)
+class PaymentResponse extends BaseAuthorizedResponse {
+
+  final PaymentDTO payment;
+
+  const PaymentResponse({required super.accessToken, required this.payment});
+
+  factory PaymentResponse.fromJson(Map<String, dynamic> json) => _$PaymentResponseFromJson(json);
+  @override
+  Map<String, dynamic> toJson() => _$PaymentResponseToJson(this);
+}

frontend/pshared/lib/data/dto/payment/intent/customer.dart

@@ -0,0 +1,41 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'customer.g.dart';
+
+
+@JsonSerializable()
+class CustomerDTO {
+  final String id;
+
+  @JsonKey(name: 'first_name')
+  final String? firstName;
+
+  @JsonKey(name: 'middle_name')
+  final String? middleName;
+
+  @JsonKey(name: 'last_name')
+  final String? lastName;
+
+  final String? ip;
+  final String? zip;
+  final String? country;
+  final String? state;
+  final String? city;
+  final String? address;
+
+  const CustomerDTO({
+    required this.id,
+    this.firstName,
+    this.middleName,
+    this.lastName,
+    this.ip,
+    this.zip,
+    this.country,
+    this.state,
+    this.city,
+    this.address,
+  });
+
+  factory CustomerDTO.fromJson(Map<String, dynamic> json) => _$CustomerDTOFromJson(json);
+  Map<String, dynamic> toJson() => _$CustomerDTOToJson(this);
+}

frontend/pshared/lib/data/dto/payment/intent/payment.dart

@@ -1,6 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 
 import 'package:pshared/data/dto/payment/endpoint.dart';
+import 'package:pshared/data/dto/payment/intent/customer.dart';
 import 'package:pshared/data/dto/payment/intent/fx.dart';
 import 'package:pshared/data/dto/payment/money.dart';
 
@@ -20,6 +21,7 @@ class PaymentIntentDTO {
   final String? settlementMode;
 
   final Map<String, String>? attributes;
+  final CustomerDTO? customer;
 
   const PaymentIntentDTO({
     this.kind,
@@ -29,6 +31,7 @@ class PaymentIntentDTO {
     this.fx,
     this.settlementMode,
     this.attributes,
+    this.customer,
   });
 
   factory PaymentIntentDTO.fromJson(Map<String, dynamic> json) => _$PaymentIntentDTOFromJson(json);

frontend/pshared/lib/data/mapper/payment/intent/customer.dart

@@ -0,0 +1,33 @@
+import 'package:pshared/data/dto/payment/intent/customer.dart';
+import 'package:pshared/models/payment/customer.dart';
+
+
+extension CustomerMapper on Customer {
+  CustomerDTO toDTO() => CustomerDTO(
+    id: id,
+    firstName: firstName,
+    middleName: middleName,
+    lastName: lastName,
+    ip: ip,
+    zip: zip,
+    country: country,
+    state: state,
+    city: city,
+    address: address,
+  );
+}
+
+extension CustomerDTOMapper on CustomerDTO {
+  Customer toDomain() => Customer(
+    id: id,
+    firstName: firstName,
+    middleName: middleName,
+    lastName: lastName,
+    ip: ip,
+    zip: zip,
+    country: country,
+    state: state,
+    city: city,
+    address: address,
+  );
+}

frontend/pshared/lib/data/mapper/payment/intent/payment.dart

@@ -1,30 +1,34 @@
 import 'package:pshared/data/dto/payment/intent/payment.dart';
 import 'package:pshared/data/mapper/payment/payment.dart';
 import 'package:pshared/data/mapper/payment/enums.dart';
+import 'package:pshared/data/mapper/payment/intent/customer.dart';
 import 'package:pshared/data/mapper/payment/intent/fx.dart';
 import 'package:pshared/data/mapper/payment/money.dart';
 import 'package:pshared/models/payment/intent.dart';
 
+
 extension PaymentIntentMapper on PaymentIntent {
   PaymentIntentDTO toDTO() => PaymentIntentDTO(
-        kind: paymentKindToValue(kind),
-        source: source?.toDTO(),
-        destination: destination?.toDTO(),
-        amount: amount?.toDTO(),
-        fx: fx?.toDTO(),
-        settlementMode: settlementModeToValue(settlementMode),
-        attributes: attributes,
-      );
+    kind: paymentKindToValue(kind),
+    source: source?.toDTO(),
+    destination: destination?.toDTO(),
+    amount: amount?.toDTO(),
+    fx: fx?.toDTO(),
+    settlementMode: settlementModeToValue(settlementMode),
+    attributes: attributes,
+    customer: customer?.toDTO(),
+  );
 }
 
 extension PaymentIntentDTOMapper on PaymentIntentDTO {
   PaymentIntent toDomain() => PaymentIntent(
-        kind: paymentKindFromValue(kind),
-        source: source?.toDomain(),
-        destination: destination?.toDomain(),
-        amount: amount?.toDomain(),
-        fx: fx?.toDomain(),
-        settlementMode: settlementModeFromValue(settlementMode),
-        attributes: attributes,
-      );
+    kind: paymentKindFromValue(kind),
+    source: source?.toDomain(),
+    destination: destination?.toDomain(),
+    amount: amount?.toDomain(),
+    fx: fx?.toDomain(),
+    settlementMode: settlementModeFromValue(settlementMode),
+    attributes: attributes,
+    customer: customer?.toDomain(),
+  );
 }

frontend/pshared/lib/models/payment/customer.dart

@@ -0,0 +1,25 @@
+class Customer {
+  final String id;
+  final String? firstName;
+  final String? middleName;
+  final String? lastName;
+  final String? ip;
+  final String? zip;
+  final String? country;
+  final String? state;
+  final String? city;
+  final String? address;
+
+  const Customer({
+    required this.id,
+    this.firstName,
+    this.middleName,
+    this.lastName,
+    this.ip,
+    this.zip,
+    this.country,
+    this.state,
+    this.city,
+    this.address,
+  });
+}

frontend/pshared/lib/models/payment/intent.dart

@@ -1,5 +1,6 @@
 import 'package:pshared/models/payment/fx/intent.dart';
 import 'package:pshared/models/payment/kind.dart';
+import 'package:pshared/models/payment/customer.dart';
 import 'package:pshared/models/payment/methods/data.dart';
 import 'package:pshared/models/payment/money.dart';
 import 'package:pshared/models/payment/settlement_mode.dart';
@@ -13,6 +14,7 @@ class PaymentIntent {
   final FxIntent? fx;
   final SettlementMode settlementMode;
   final Map<String, String>? attributes;
+  final Customer? customer;
 
   const PaymentIntent({
     this.kind = PaymentKind.unspecified,
@@ -22,5 +24,6 @@ class PaymentIntent {
     this.fx,
     this.settlementMode = SettlementMode.unspecified,
     this.attributes,
+    this.customer,
   });
 }

frontend/pshared/lib/provider/payment/flow.dart

@@ -1,73 +1,63 @@
+import 'package:collection/collection.dart';
 import 'package:flutter/foundation.dart';
 
 import 'package:pshared/models/payment/methods/data.dart';
+import 'package:pshared/models/payment/methods/type.dart';
 import 'package:pshared/models/payment/type.dart';
 import 'package:pshared/models/recipient/recipient.dart';
+import 'package:pshared/provider/recipient/provider.dart';
+import 'package:pshared/provider/recipient/pmethods.dart';
 
 
 class PaymentFlowProvider extends ChangeNotifier {
   PaymentType _selectedType;
+  PaymentType? _preferredType;
   PaymentMethodData? _manualPaymentData;
+  List<PaymentMethod> _recipientMethods = [];
+  Recipient? _recipient;
 
   PaymentFlowProvider({
     required PaymentType initialType,
-  }) : _selectedType = initialType;
+    PaymentType? preferredType,
+  })  : _selectedType = initialType,
+        _preferredType = preferredType ?? initialType;
 
   PaymentType get selectedType => _selectedType;
   PaymentMethodData? get manualPaymentData => _manualPaymentData;
+  Recipient? get recipient => _recipient;
+  PaymentMethod? get selectedMethod => hasRecipient
+      ? _recipientMethods.firstWhereOrNull((method) => method.type == _selectedType)
+      : null;
 
-  void sync({
-    required Recipient? recipient,
-    required MethodMap availableTypes,
-    PaymentType? preferredType,
-  }) {
-    final resolvedType = _resolveSelectedType(
-      recipient: recipient,
-      availableTypes: availableTypes,
-      preferredType: preferredType,
-    );
+  bool get hasRecipient => _recipient != null;
 
-    var hasChanges = false;
-    if (resolvedType != _selectedType) {
-      _selectedType = resolvedType;
-      hasChanges = true;
-    }
+  MethodMap get availableTypes => hasRecipient
+      ? _buildAvailableTypes(_recipientMethods)
+      : {for (final type in PaymentType.values) type: null};
 
-    if (recipient != null && _manualPaymentData != null) {
-      _manualPaymentData = null;
-      hasChanges = true;
-    }
+  PaymentMethodData? get selectedPaymentData =>
+      hasRecipient ? selectedMethod?.data : _manualPaymentData;
 
-    if (hasChanges) notifyListeners();
-  }
+  List<PaymentMethod> get methodsForRecipient => hasRecipient
+      ? List<PaymentMethod>.unmodifiable(_recipientMethods)
+      : const [];
 
-  void reset({
-    required Recipient? recipient,
-    required MethodMap availableTypes,
-    PaymentType? preferredType,
-  }) {
-    final resolvedType = _resolveSelectedType(
-      recipient: recipient,
-      availableTypes: availableTypes,
-      preferredType: preferredType,
-    );
-
-    var hasChanges = false;
-
-    if (resolvedType != _selectedType) {
-      _selectedType = resolvedType;
-      hasChanges = true;
-    }
-
-    if (_manualPaymentData != null) {
-      _manualPaymentData = null;
-      hasChanges = true;
-    }
-
-    if (hasChanges) notifyListeners();
-  }
+  void update(
+    RecipientsProvider recipientsProvider,
+    PaymentMethodsProvider methodsProvider,
+  ) =>
+      _applyState(
+        recipient: recipientsProvider.currentObject,
+        methods: methodsProvider.methodsForRecipient(recipientsProvider.currentObject),
+        preferredType: _preferredType,
+        forceResetManualData: false,
+      );
 
   void selectType(PaymentType type, {bool resetManualData = false}) {
+    if (hasRecipient && !availableTypes.containsKey(type)) {
+      return;
+    }
+
     if (_selectedType == type && (!resetManualData || _manualPaymentData == null)) {
       return;
     }
@@ -84,6 +74,20 @@ class PaymentFlowProvider extends ChangeNotifier {
     notifyListeners();
   }
 
+  void setPreferredType(PaymentType? preferredType) {
+    if (_preferredType == preferredType) {
+      return;
+    }
+
+    _preferredType = preferredType;
+    _applyState(
+      recipient: _recipient,
+      methods: _recipientMethods,
+      preferredType: _preferredType,
+      forceResetManualData: false,
+    );
+  }
+
   PaymentType _resolveSelectedType({
     required Recipient? recipient,
     required MethodMap availableTypes,
@@ -107,4 +111,56 @@ class PaymentFlowProvider extends ChangeNotifier {
 
     return availableTypes.keys.first;
   }
+
+  void _applyState({
+    required Recipient? recipient,
+    required List<PaymentMethod> methods,
+    required PaymentType? preferredType,
+    required bool forceResetManualData,
+  }) {
+    final availableTypes = _buildAvailableTypes(methods);
+    final resolvedType = _resolveSelectedType(
+      recipient: recipient,
+      availableTypes: availableTypes,
+      preferredType: preferredType,
+    );
+
+    var hasChanges = false;
+
+    if (_recipient != recipient) {
+      _recipient = recipient;
+      hasChanges = true;
+    }
+
+    if (!_hasSameMethods(methods)) {
+      _recipientMethods = methods;
+      hasChanges = true;
+    }
+
+    if (resolvedType != _selectedType) {
+      _selectedType = resolvedType;
+      hasChanges = true;
+    }
+
+    if ((recipient != null || forceResetManualData) && _manualPaymentData != null) {
+      _manualPaymentData = null;
+      hasChanges = true;
+    }
+
+    if (hasChanges) notifyListeners();
+  }
+
+  MethodMap _buildAvailableTypes(List<PaymentMethod> methods) => {
+        for (final method in methods) method.type: method.data,
+      };
+
+  bool _hasSameMethods(List<PaymentMethod> methods) {
+    if (_recipientMethods.length != methods.length) return false;
+    for (var i = 0; i < methods.length; i++) {
+      final current = _recipientMethods[i];
+      final next = methods[i];
+      if (current.id != next.id || current.updatedAt != next.updatedAt) return false;
+    }
+    return true;
+  }
 }

frontend/pshared/lib/provider/payment/provider.dart

@@ -0,0 +1,64 @@
+import 'package:flutter/foundation.dart';
+
+import 'package:pshared/models/payment/payment.dart';
+import 'package:pshared/provider/organizations.dart';
+import 'package:pshared/provider/payment/quotation.dart';
+import 'package:pshared/provider/resource.dart';
+import 'package:pshared/service/payment/service.dart';
+
+
+class PaymentProvider extends ChangeNotifier {
+  late OrganizationsProvider _organization;
+  late QuotationProvider _quotation;
+
+  Resource<Payment> _payment = Resource(data: null, isLoading: false, error: null);
+  bool _isLoaded = false;
+
+  void update(OrganizationsProvider organization, QuotationProvider quotation) {
+    _quotation = quotation;
+    _organization = organization;
+  }
+
+  Payment? get payment => _payment.data;
+  bool get isLoading => _payment.isLoading;
+  Exception? get error => _payment.error;
+  bool get isReady => _isLoaded && !_payment.isLoading && _payment.error == null;
+
+  void _setResource(Resource<Payment> payment) {
+    _payment = payment;
+    notifyListeners();
+  }
+
+  Future<Payment?> pay({String? idempotencyKey, Map<String, String>? metadata}) async {
+    if (!_organization.isOrganizationSet) throw StateError('Organization is not set');
+    if (!_quotation.isReady) throw StateError('Quotation is not ready');
+    final quoteRef = _quotation.quotation?.quoteRef;
+    if (quoteRef == null || quoteRef.isEmpty) {
+      throw StateError('Quotation reference is not set');
+    }
+
+    _setResource(_payment.copyWith(isLoading: true, error: null));
+    try {
+      final response = await PaymentService.pay(
+        _organization.current.id,
+        quoteRef,
+        idempotencyKey: idempotencyKey,
+        metadata: metadata,
+      );
+      _isLoaded = true;
+      _setResource(_payment.copyWith(data: response, isLoading: false, error: null));
+    } catch (e) {
+      _setResource(_payment.copyWith(
+        data: null,
+        error: e is Exception ? e : Exception(e.toString()),
+        isLoading: false,
+      ));
+    }
+    return _payment.data;
+  }
+
+  void reset() {
+    _setResource(Resource(data: null, isLoading: false, error: null));
+    _isLoaded = false;
+  }
+}

frontend/pshared/lib/provider/payment/quotation.dart

@@ -8,18 +8,22 @@ import 'package:pshared/api/requests/payment/quote.dart';
 import 'package:pshared/data/mapper/payment/intent/payment.dart';
 import 'package:pshared/models/asset.dart';
 import 'package:pshared/models/payment/currency_pair.dart';
+import 'package:pshared/models/payment/customer.dart';
 import 'package:pshared/models/payment/fx/intent.dart';
 import 'package:pshared/models/payment/fx/side.dart';
 import 'package:pshared/models/payment/kind.dart';
 import 'package:pshared/models/payment/methods/managed_wallet.dart';
+import 'package:pshared/models/payment/methods/type.dart';
 import 'package:pshared/models/payment/money.dart';
 import 'package:pshared/models/payment/settlement_mode.dart';
 import 'package:pshared/models/payment/intent.dart';
 import 'package:pshared/models/payment/quote.dart';
+import 'package:pshared/models/recipient/recipient.dart';
 import 'package:pshared/provider/organizations.dart';
 import 'package:pshared/provider/payment/amount.dart';
 import 'package:pshared/provider/payment/flow.dart';
 import 'package:pshared/provider/payment/wallets.dart';
+import 'package:pshared/provider/recipient/provider.dart';
 import 'package:pshared/provider/recipient/pmethods.dart';
 import 'package:pshared/provider/resource.dart';
 import 'package:pshared/service/payment/quotation.dart';
@@ -36,12 +40,17 @@ class QuotationProvider extends ChangeNotifier {
     PaymentAmountProvider payment,
     WalletsProvider wallets,
     PaymentFlowProvider flow,
+    RecipientsProvider recipients,
     PaymentMethodsProvider methods,
   ) {
     _organizations = venue;
     final t = flow.selectedType;
     final method = methods.methods.firstWhereOrNull((m) => m.type == t);
     if ((wallets.selectedWallet != null) && (method != null)) {
+      final customer = _buildCustomer(
+        recipient: recipients.currentObject,
+        method: method,
+      );
       getQuotation(PaymentIntent(
         kind: PaymentKind.payout,
         amount: Money(
@@ -61,6 +70,7 @@ class QuotationProvider extends ChangeNotifier {
           side: FxSide.sellBaseBuyQuote,
         ),
         settlementMode: payment.payerCoversFee ? SettlementMode.fixReceived : SettlementMode.fixSource,
+        customer: customer,
       ));
     }
   }
@@ -73,6 +83,58 @@ class QuotationProvider extends ChangeNotifier {
   Asset? get total => quotation == null ? null : createAsset(quotation!.debitAmount!.currency, quotation!.debitAmount!.amount);
   Asset? get recipientGets => quotation == null ? null : createAsset(quotation!.expectedSettlementAmount!.currency, quotation!.expectedSettlementAmount!.amount);
 
+  Customer _buildCustomer({
+    required Recipient? recipient,
+    required PaymentMethod method,
+  }) {
+    final name = _resolveCustomerName(method, recipient);
+    String? firstName;
+    String? middleName;
+    String? lastName;
+
+    if (name != null && name.isNotEmpty) {
+      final parts = name.split(RegExp(r'\s+'));
+      if (parts.length == 1) {
+        firstName = parts.first;
+      } else if (parts.length == 2) {
+        firstName = parts.first;
+        lastName = parts.last;
+      } else {
+        firstName = parts.first;
+        lastName = parts.last;
+        middleName = parts.sublist(1, parts.length - 1).join(' ');
+      }
+    }
+
+    return Customer(
+      id: recipient?.id ?? method.recipientRef,
+      firstName: firstName,
+      middleName: middleName,
+      lastName: lastName,
+      country: method.cardData?.country,
+    );
+  }
+
+  String? _resolveCustomerName(PaymentMethod method, Recipient? recipient) {
+    final card = method.cardData;
+    if (card != null) {
+      return '${card.firstName} ${card.lastName}'.trim();
+    }
+
+    final iban = method.ibanData;
+    if (iban != null && iban.accountHolder.trim().isNotEmpty) {
+      return iban.accountHolder.trim();
+    }
+
+    final bank = method.bankAccountData;
+    if (bank != null && bank.recipientName.trim().isNotEmpty) {
+      return bank.recipientName.trim();
+    }
+
+    final recipientName = recipient?.name.trim();
+    return recipientName?.isNotEmpty == true ? recipientName : null;
+  }
+
   void _setResource(Resource<PaymentQuote> quotation) {
     _quotation = quotation;
     notifyListeners();

frontend/pshared/lib/provider/payment/wallets.dart

@@ -1,3 +1,4 @@
+import 'package:collection/collection.dart';
 import 'package:flutter/material.dart';
 
 import 'package:pshared/models/payment/wallet.dart';
@@ -38,10 +39,7 @@ class WalletsProvider with ChangeNotifier {
     throw Exception('update wallet is not implemented');
   }
 
-  void selectWallet(Wallet wallet) {
-    _selectedWallet = wallet;
-    notifyListeners();
-  }
+  void selectWallet(Wallet wallet) => _setSelectedWallet(wallet);
 
   Future<void> loadWalletsWithBalances() async {
     _setResource(_resource.copyWith(isLoading: true, error: null));
@@ -98,6 +96,25 @@ class WalletsProvider with ChangeNotifier {
 
   void _setResource(Resource<List<Wallet>> newResource) {
     _resource = newResource;
+    _selectedWallet = _resolveSelectedWallet(_selectedWallet, wallets);
+    notifyListeners();
+  }
+
+  Wallet? _resolveSelectedWallet(Wallet? current, List<Wallet> available) {
+    if (available.isEmpty) return null;
+    final currentId = current?.id;
+    if (currentId != null) {
+      final existing = available.firstWhereOrNull((wallet) => wallet.id == currentId);
+      if (existing != null) return existing;
+    }
+    return available.firstWhereOrNull((wallet) => !wallet.isHidden) ?? available.first;
+  }
+
+  void _setSelectedWallet(Wallet wallet) {
+    if (_selectedWallet?.id == wallet.id && _selectedWallet?.isHidden == wallet.isHidden) {
+      return;
+    }
+    _selectedWallet = wallet;
     notifyListeners();
   }
 }

frontend/pshared/lib/provider/recipient/pmethods.dart

@@ -5,6 +5,8 @@ import 'package:pshared/models/describable.dart';
 import 'package:pshared/models/organization/bound.dart';
 import 'package:pshared/models/payment/methods/data.dart';
 import 'package:pshared/models/payment/methods/type.dart';
+import 'package:pshared/models/payment/type.dart';
+import 'package:pshared/models/recipient/recipient.dart';
 import 'package:pshared/models/permissions/bound.dart';
 import 'package:pshared/models/storable.dart';
 import 'package:pshared/provider/organizations.dart';
@@ -20,6 +22,24 @@ class PaymentMethodsProvider extends GenericProvider<PaymentMethod> {
 
   List<PaymentMethod> get methods => List<PaymentMethod>.unmodifiable(items.toList()..sort((a, b) => a.storable.createdAt.compareTo(b.storable.createdAt))); 
 
+  List<PaymentMethod> methodsForRecipient(Recipient? recipient) {
+    if (recipient == null || !isReady) return [];
+
+    return methods
+        .where((method) => !method.isArchived && method.recipientRef == recipient.id)
+        .toList();
+  }
+
+  MethodMap availableTypesForRecipient(Recipient? recipient) => {
+    for (final method in methodsForRecipient(recipient)) method.type: method.data,
+  };
+
+  PaymentMethod? findMethodByType({
+    required PaymentType type,
+    required Recipient? recipient,
+  }) =>
+      methodsForRecipient(recipient).firstWhereOrNull((method) => method.type == type);
+
   void updateProviders(OrganizationsProvider organizations, RecipientsProvider recipients) {
     if (recipients.currentObject != null) loadMethods(organizations, recipients.currentObject?.id);
   }

frontend/pshared/lib/provider/recipient/provider.dart

@@ -14,6 +14,7 @@ class RecipientsProvider extends GenericProvider<Recipient> {
 
   RecipientFilter _selectedFilter = RecipientFilter.all;
   String _query = '';
+  String? _previousRecipientRef;
 
   RecipientFilter get selectedFilter => _selectedFilter;
   String get query => _query;
@@ -22,6 +23,10 @@ class RecipientsProvider extends GenericProvider<Recipient> {
 
   RecipientsProvider() : super(service: RecipientService.basicService);
 
+  Recipient? get previousRecipient => _previousRecipientRef == null
+      ? null
+      : getItemByRef(_previousRecipientRef!);
+
   List<Recipient> get filteredRecipients {
     List<Recipient> filtered = recipients.where((r) {
       switch (_selectedFilter) {
@@ -53,6 +58,24 @@ class RecipientsProvider extends GenericProvider<Recipient> {
     notifyListeners();
   }
 
+  @override
+  bool setCurrentObject(String? objectRef) {
+    final currentRef = currentObject?.id;
+    final didUpdate = super.setCurrentObject(objectRef);
+
+    if (didUpdate && currentRef != null && currentRef != objectRef) {
+      _previousRecipientRef = currentRef;
+    }
+
+    return didUpdate;
+  }
+
+  void restorePreviousRecipient() {
+    if (_previousRecipientRef != null) {
+      setCurrentObject(_previousRecipientRef);
+    }
+  }
+
   Future<Recipient> create({
     required String name,
     required String email,

frontend/pshared/lib/service/payment/service.dart

@@ -0,0 +1,35 @@
+import 'package:logging/logging.dart';
+import 'package:uuid/uuid.dart';
+
+import 'package:pshared/api/requests/payment/initiate.dart';
+import 'package:pshared/api/responses/payment/payment.dart';
+import 'package:pshared/data/mapper/payment/payment_response.dart';
+import 'package:pshared/models/payment/payment.dart';
+import 'package:pshared/service/authorization/service.dart';
+import 'package:pshared/service/services.dart';
+
+
+class PaymentService {
+  static final _logger = Logger('service.payment');
+  static const String _objectType = Services.payments;
+
+  static Future<Payment> pay(
+    String organizationRef,
+    String quotationRef, {
+    String? idempotencyKey,
+    Map<String, String>? metadata,
+  }) async {
+    _logger.fine('Executing payment for quotation $quotationRef in $organizationRef');
+    final request = InitiatePaymentRequest(
+      idempotencyKey: idempotencyKey ?? Uuid().v4(),
+      quoteRef: quotationRef,
+      metadata: metadata,
+    );
+    final response = await AuthorizationService.getPOSTResponse(
+      _objectType,
+      '/by-quote/$organizationRef',
+      request.toJson(),
+    );
+    return PaymentResponse.fromJson(response).payment.toDomain();
+  }
+}

frontend/pweb/lib/main.dart

@@ -13,23 +13,26 @@ import 'package:pshared/provider/permissions.dart';
 import 'package:pshared/provider/account.dart';
 import 'package:pshared/provider/organizations.dart';
 import 'package:pshared/provider/payment/amount.dart';
+import 'package:pshared/provider/payment/flow.dart';
+import 'package:pshared/provider/payment/provider.dart';
+import 'package:pshared/provider/payment/quotation.dart';
 import 'package:pshared/provider/recipient/provider.dart';
 import 'package:pshared/provider/recipient/pmethods.dart';
+import 'package:pshared/provider/payment/wallets.dart';
+import 'package:pshared/models/payment/type.dart';
+import 'package:pshared/service/payment/wallets.dart';
 
 import 'package:pweb/app/app.dart';
 import 'package:pweb/app/timeago.dart';
 import 'package:pweb/providers/carousel.dart';
-import 'package:pweb/providers/mock_payment.dart';
 import 'package:pweb/providers/operatioins.dart';
 import 'package:pweb/providers/two_factor.dart';
 import 'package:pweb/providers/upload_history.dart';
-import 'package:pshared/provider/payment/wallets.dart';
 import 'package:pweb/providers/wallet_transactions.dart';
 import 'package:pweb/services/operations.dart';
 import 'package:pweb/services/payments/history.dart';
 import 'package:pweb/services/posthog.dart';
 import 'package:pweb/services/wallet_transactions.dart';
-import 'package:pshared/service/payment/wallets.dart';
 import 'package:pweb/providers/account.dart';
 
 
@@ -89,16 +92,31 @@ void main() async {
         ChangeNotifierProvider(
           create: (_) => WalletTransactionsProvider(MockWalletTransactionsService())..load(),
         ),
-        ChangeNotifierProvider(
-          create: (_) => MockPaymentProvider(),
+        ChangeNotifierProxyProvider2<RecipientsProvider, PaymentMethodsProvider, PaymentFlowProvider>(
+          create: (_) => PaymentFlowProvider(initialType: PaymentType.bankAccount),
+          update: (context, recipients, methods, provider) => provider!..update(
+            recipients,
+            methods,
+          ),
         ),
-        
         ChangeNotifierProvider(
           create: (_) => OperationProvider(OperationService())..loadOperations(),
         ),
         ChangeNotifierProvider(
           create: (_) => PaymentAmountProvider(),
         ),
+        ChangeNotifierProxyProvider6<OrganizationsProvider, PaymentAmountProvider, WalletsProvider, PaymentFlowProvider, RecipientsProvider, PaymentMethodsProvider, QuotationProvider>(
+          create: (_) => QuotationProvider(),
+          update: (_, organization, payment, wallet, flow, recipients, methods, provider) =>
+              provider!..update(organization, payment, wallet, flow, recipients, methods),
+        ),
+        ChangeNotifierProxyProvider2<OrganizationsProvider, QuotationProvider, PaymentProvider>(
+          create: (_) => PaymentProvider(),
+          update: (context, organization, quotation, provider) => provider!..update(
+            organization,
+            quotation,
+          ),
+        ),
       ],
       child: const PayApp(),
     ),

frontend/pweb/lib/pages/dashboard/payouts/widget.dart

@@ -1,14 +1,5 @@
 import 'package:flutter/material.dart';
 
-import 'package:provider/provider.dart';
-
-import 'package:pshared/provider/organizations.dart';
-import 'package:pshared/provider/payment/amount.dart';
-import 'package:pshared/provider/payment/flow.dart';
-import 'package:pshared/provider/payment/quotation.dart';
-import 'package:pshared/provider/payment/wallets.dart';
-import 'package:pshared/provider/recipient/pmethods.dart';
-
 import 'package:pweb/pages/dashboard/payouts/form.dart';
 
 
@@ -16,16 +7,5 @@ class PaymentFromWrappingWidget extends StatelessWidget {
   const PaymentFromWrappingWidget({super.key});
 
   @override
-  Widget build(BuildContext context) => MultiProvider(
-    providers: [
-      ChangeNotifierProvider(
-        create: (_) => PaymentAmountProvider(),
-      ),
-      ChangeNotifierProxyProvider5<OrganizationsProvider, PaymentAmountProvider, WalletsProvider, PaymentFlowProvider, PaymentMethodsProvider, QuotationProvider>(
-        create: (_) => QuotationProvider(),
-        update: (context, orgnization, payment, wallet, flow, methods, provider) => provider!..update(orgnization, payment, wallet, flow, methods),
-      ),
-    ],
-    child: const PaymentFormWidget(),
-  );
-}
+  Widget build(BuildContext context) => const PaymentFormWidget();
+}

frontend/pweb/lib/pages/payment_methods/add/card.dart

@@ -67,10 +67,17 @@ class _CardFormMinimalState extends State<CardFormMinimal> {
     }
 
     if (newData != null && newData != oldData) {
-      _panController.text = newData.pan;
-      _firstNameController.text = newData.firstName;
-      _lastNameController.text = newData.lastName;
-      WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      final hasPanChange = newData.pan != _panController.text;
+      final hasFirstNameChange = newData.firstName != _firstNameController.text;
+      final hasLastNameChange = newData.lastName != _lastNameController.text;
+
+      if (hasPanChange) _panController.text = newData.pan;
+      if (hasFirstNameChange) _firstNameController.text = newData.firstName;
+      if (hasLastNameChange) _lastNameController.text = newData.lastName;
+
+      if (hasPanChange || hasFirstNameChange || hasLastNameChange) {
+        WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      }
     }
   }
 

frontend/pweb/lib/pages/payment_methods/add/crypto_address.dart

@@ -106,12 +106,21 @@ class _CryptoAddressFormState extends State<CryptoAddressForm> {
     }
 
     if (newData != null && newData != oldData) {
-      _addressCtrl.text = newData.address;
-      _tokenCtrl.text = newData.asset?.tokenSymbol ?? '';
-      _contractCtrl.text = newData.asset?.contractAddress ?? '';
-      _memoCtrl.text = newData.memo ?? '';
-      _chain = newData.asset?.chain ?? ChainNetwork.unspecified;
-      WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      final hasAddressChange = newData.address != _addressCtrl.text;
+      final hasTokenChange = newData.asset?.tokenSymbol != _tokenCtrl.text;
+      final hasContractChange = newData.asset?.contractAddress != _contractCtrl.text;
+      final hasMemoChange = newData.memo != _memoCtrl.text;
+      final hasChainChange = newData.asset?.chain != _chain;
+
+      if (hasAddressChange) _addressCtrl.text = newData.address;
+      if (hasTokenChange) _tokenCtrl.text = newData.asset?.tokenSymbol ?? '';
+      if (hasContractChange) _contractCtrl.text = newData.asset?.contractAddress ?? '';
+      if (hasMemoChange) _memoCtrl.text = newData.memo ?? '';
+      if (hasChainChange) _chain = newData.asset?.chain ?? ChainNetwork.unspecified;
+
+      if (hasAddressChange || hasTokenChange || hasContractChange || hasMemoChange || hasChainChange) {
+        WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      }
     }
   }
 

frontend/pweb/lib/pages/payment_methods/add/iban.dart

@@ -69,11 +69,19 @@ class _IbanFormState extends State<IbanForm> {
     }
 
     if (newData != null && newData != oldData) {
-      _ibanController.text = newData.iban;
-      _accountHolderController.text = newData.accountHolder;
-      _bicController.text = newData.bic ?? '';
-      _bankNameController.text = newData.bankName ?? '';
-      WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      final hasIbanChange = newData.iban != _ibanController.text;
+      final hasHolderChange = newData.accountHolder != _accountHolderController.text;
+      final hasBicChange = (newData.bic ?? '') != _bicController.text;
+      final hasBankNameChange = (newData.bankName ?? '') != _bankNameController.text;
+
+      if (hasIbanChange) _ibanController.text = newData.iban;
+      if (hasHolderChange) _accountHolderController.text = newData.accountHolder;
+      if (hasBicChange) _bicController.text = newData.bic ?? '';
+      if (hasBankNameChange) _bankNameController.text = newData.bankName ?? '';
+
+      if (hasIbanChange || hasHolderChange || hasBicChange || hasBankNameChange) {
+        WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      }
     }
   }
 

frontend/pweb/lib/pages/payment_methods/add/russian_bank.dart

@@ -82,14 +82,31 @@ class _RussianBankFormState extends State<RussianBankForm> {
     }
 
     if (newData != null && newData != oldData) {
-      _recipientNameController.text = newData.recipientName;
-      _innController.text = newData.inn;
-      _kppController.text = newData.kpp;
-      _bankNameController.text = newData.bankName;
-      _bikController.text = newData.bik;
-      _accountNumberController.text = newData.accountNumber;
-      _correspondentAccountController.text = newData.correspondentAccount;
-      WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      final hasRecipientNameChange = newData.recipientName != _recipientNameController.text;
+      final hasInnChange = newData.inn != _innController.text;
+      final hasKppChange = newData.kpp != _kppController.text;
+      final hasBankNameChange = newData.bankName != _bankNameController.text;
+      final hasBikChange = newData.bik != _bikController.text;
+      final hasAccountNumberChange = newData.accountNumber != _accountNumberController.text;
+      final hasCorrespondentAccountChange = newData.correspondentAccount != _correspondentAccountController.text;
+
+      if (hasRecipientNameChange) _recipientNameController.text = newData.recipientName;
+      if (hasInnChange) _innController.text = newData.inn;
+      if (hasKppChange) _kppController.text = newData.kpp;
+      if (hasBankNameChange) _bankNameController.text = newData.bankName;
+      if (hasBikChange) _bikController.text = newData.bik;
+      if (hasAccountNumberChange) _accountNumberController.text = newData.accountNumber;
+      if (hasCorrespondentAccountChange) _correspondentAccountController.text = newData.correspondentAccount;
+
+      if (hasRecipientNameChange ||
+          hasInnChange ||
+          hasKppChange ||
+          hasBankNameChange ||
+          hasBikChange ||
+          hasAccountNumberChange ||
+          hasCorrespondentAccountChange) {
+        WidgetsBinding.instance.addPostFrameCallback((_) => _emitIfValid());
+      }
     }
   }
 

frontend/pweb/lib/pages/payment_methods/add/wallet.dart

@@ -51,7 +51,9 @@ class _WalletFormState extends State<WalletForm> {
     }
 
     if (newData != null && newData != oldData) {
-      _walletIdController.text = newData.walletId;
+      if (newData.walletId != _walletIdController.text) {
+        _walletIdController.text = newData.walletId;
+      }
     }
   }
 

frontend/pweb/lib/pages/payment_methods/page.dart

@@ -1,20 +1,16 @@
 import 'package:flutter/material.dart';
 
-import 'package:collection/collection.dart';
-
 import 'package:provider/provider.dart';
 
-import 'package:pshared/models/payment/methods/data.dart';
-import 'package:pshared/models/payment/methods/type.dart';
 import 'package:pshared/models/payment/type.dart';
 import 'package:pshared/models/recipient/recipient.dart';
 import 'package:pshared/provider/payment/flow.dart';
+import 'package:pshared/provider/payment/provider.dart';
 import 'package:pshared/provider/recipient/pmethods.dart';
 import 'package:pshared/provider/recipient/provider.dart';
-
-import 'package:pshared/models/payment/wallet.dart';
-import 'package:pweb/pages/payment_methods/payment_page/body.dart';
 import 'package:pshared/provider/payment/wallets.dart';
+
+import 'package:pweb/pages/payment_methods/payment_page/body.dart';
 import 'package:pweb/widgets/sidebar/destinations.dart';
 import 'package:pweb/services/posthog.dart';
 
@@ -38,16 +34,12 @@ class PaymentPage extends StatefulWidget {
 class _PaymentPageState extends State<PaymentPage> {
   late final TextEditingController _searchController;
   late final FocusNode _searchFocusNode;
-  late final PaymentFlowProvider _flowProvider;
 
   @override
   void initState() {
     super.initState();
     _searchController = TextEditingController();
     _searchFocusNode = FocusNode();
-    _flowProvider = PaymentFlowProvider(
-      initialType: widget.initialPaymentType ?? PaymentType.bankAccount,
-    );
 
     WidgetsBinding.instance.addPostFrameCallback((_) => _initializePaymentPage());
   }
@@ -56,20 +48,12 @@ class _PaymentPageState extends State<PaymentPage> {
   void dispose() {
     _searchController.dispose();
     _searchFocusNode.dispose();
-    _flowProvider.dispose();
     super.dispose();
   }
 
   void _initializePaymentPage() {
-    final methodsProvider = context.read<PaymentMethodsProvider>();
-    _handleWalletAutoSelection(methodsProvider);
-
-    final recipient = context.read<RecipientsProvider>().currentObject;
-    _syncFlowProvider(
-      recipient: recipient,
-      methodsProvider: methodsProvider,
-      preferredType: widget.initialPaymentType,
-    );
+    final flowProvider = context.read<PaymentFlowProvider>();
+    flowProvider.setPreferredType(widget.initialPaymentType);
   }
 
   void _handleSearchChanged(String query) {
@@ -78,27 +62,13 @@ class _PaymentPageState extends State<PaymentPage> {
 
   void _handleRecipientSelected(Recipient recipient) {
     final recipientProvider = context.read<RecipientsProvider>();
-    final methodsProvider = context.read<PaymentMethodsProvider>();
-
     recipientProvider.setCurrentObject(recipient.id);
-    _flowProvider.reset(
-      recipient: recipient,
-      availableTypes: _availablePaymentTypes(recipient, methodsProvider),
-      preferredType: widget.initialPaymentType,
-    );
     _clearSearchField();
   }
 
   void _handleRecipientCleared() {
     final recipientProvider = context.read<RecipientsProvider>();
-    final methodsProvider = context.read<PaymentMethodsProvider>();
-
     recipientProvider.setCurrentObject(null);
-    _flowProvider.reset(
-      recipient: null,
-      availableTypes: _availablePaymentTypes(null, methodsProvider),
-      preferredType: widget.initialPaymentType,
-    );
     _clearSearchField();
   }
 
@@ -109,91 +79,41 @@ class _PaymentPageState extends State<PaymentPage> {
   }
 
   void _handleSendPayment() {
-    // TODO: Handle Payment logic
-    PosthogService.paymentInitiated(method: _flowProvider.selectedType);
+    final flowProvider = context.read<PaymentFlowProvider>();
+    final paymentProvider = context.read<PaymentProvider>();
+    if (paymentProvider.isLoading) return;
+
+    paymentProvider.pay().then((_) {
+      PosthogService.paymentInitiated(method: flowProvider.selectedType);
+    }).catchError((error) {
+      if (!mounted) return;
+      ScaffoldMessenger.of(context).showSnackBar(
+        SnackBar(content: Text(error.toString())),
+      );
+    });
   }
 
   @override
   Widget build(BuildContext context) {
     final methodsProvider = context.watch<PaymentMethodsProvider>();
-    final recipientProvider = context.watch<RecipientsProvider>();
-    final recipient = recipientProvider.currentObject;
-    final availableTypes = _availablePaymentTypes(recipient, methodsProvider);
+    final recipientProvider = context.read<RecipientsProvider>();
+    final recipient = context.select<RecipientsProvider, Recipient?>(
+      (provider) => provider.currentObject,
+    );
 
-    _syncFlowProvider(
+    return PaymentPageBody(
+      onBack: widget.onBack,
+      fallbackDestination: widget.fallbackDestination,
       recipient: recipient,
+      recipientProvider: recipientProvider,
       methodsProvider: methodsProvider,
-      preferredType: recipient != null ? widget.initialPaymentType : null,
-    );
-
-    return ChangeNotifierProvider.value(
-      value: _flowProvider,
-      child: PaymentPageBody(
-        onBack: widget.onBack,
-        fallbackDestination: widget.fallbackDestination,
-        recipient: recipient,
-        recipientProvider: recipientProvider,
-        methodsProvider: methodsProvider,
-        availablePaymentTypes: availableTypes,
-        searchController: _searchController,
-        searchFocusNode: _searchFocusNode,
-        onSearchChanged: _handleSearchChanged,
-        onRecipientSelected: _handleRecipientSelected,
-        onRecipientCleared: _handleRecipientCleared,
-        onSend: _handleSendPayment,
-      ),
-    );
-  }
-
-  void _handleWalletAutoSelection(PaymentMethodsProvider methodsProvider) {
-    final wallet = context.read<WalletsProvider>().selectedWallet;
-    if (wallet == null) return;
-
-    final matchingMethod = _getPaymentMethodForWallet(wallet, methodsProvider);
-    if (matchingMethod != null) {
-      methodsProvider.setCurrentObject(matchingMethod.id);
-    }
-  }
-
-  void _syncFlowProvider({
-    required Recipient? recipient,
-    required PaymentMethodsProvider methodsProvider,
-    PaymentType? preferredType,
-  }) {
-    _flowProvider.sync(
-      recipient: recipient,
-      availableTypes: _availablePaymentTypes(recipient, methodsProvider),
-      preferredType: preferredType,
-    );
-  }
-
-  MethodMap _availablePaymentTypes(
-    Recipient? recipient,
-    PaymentMethodsProvider methodsProvider,
-  ) {
-    if (recipient == null || !methodsProvider.isReady) return {};
-
-    final methodsForRecipient = methodsProvider.methods.where(
-      (method) => !method.isArchived && method.recipientRef == recipient.id,
-    );
-
-    return {
-      for (final method in methodsForRecipient) method.type: method.data,
-    };
-  }
-
-  PaymentMethod? _getPaymentMethodForWallet(
-    Wallet wallet,
-    PaymentMethodsProvider methodsProvider,
-  ) {
-    if (methodsProvider.methods.isEmpty) {
-      return null;
-    }
-
-    return methodsProvider.methods.firstWhereOrNull(
-      (method) =>
-          method.type == PaymentType.wallet &&
-          (method.description?.contains(wallet.walletUserID) ?? false),
+      onWalletSelected: context.read<WalletsProvider>().selectWallet,
+      searchController: _searchController,
+      searchFocusNode: _searchFocusNode,
+      onSearchChanged: _handleSearchChanged,
+      onRecipientSelected: _handleRecipientSelected,
+      onRecipientCleared: _handleRecipientCleared,
+      onSend: _handleSendPayment,
     );
   }
 }

frontend/pweb/lib/pages/payment_methods/payment_page/body.dart

@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 
-import 'package:pshared/models/payment/methods/data.dart';
 import 'package:pshared/models/recipient/recipient.dart';
+import 'package:pshared/models/payment/wallet.dart';
 import 'package:pshared/provider/recipient/pmethods.dart';
 import 'package:pshared/provider/recipient/provider.dart';
 
@@ -17,7 +17,7 @@ class PaymentPageBody extends StatelessWidget {
   final Recipient? recipient;
   final RecipientsProvider recipientProvider;
   final PaymentMethodsProvider methodsProvider;
-  final MethodMap availablePaymentTypes;
+  final ValueChanged<Wallet> onWalletSelected;
   final PayoutDestination fallbackDestination;
   final TextEditingController searchController;
   final FocusNode searchFocusNode;
@@ -32,7 +32,7 @@ class PaymentPageBody extends StatelessWidget {
     required this.recipient,
     required this.recipientProvider,
     required this.methodsProvider,
-    required this.availablePaymentTypes,
+    required this.onWalletSelected,
     required this.fallbackDestination,
     required this.searchController,
     required this.searchFocusNode,
@@ -60,8 +60,7 @@ class PaymentPageBody extends StatelessWidget {
       onBack: onBack,
       recipient: recipient,
       recipientProvider: recipientProvider,
-      methodsProvider: methodsProvider,
-      availablePaymentTypes: availablePaymentTypes,
+      onWalletSelected: onWalletSelected,
       fallbackDestination: fallbackDestination,
       searchController: searchController,
       searchFocusNode: searchFocusNode,

frontend/pweb/lib/pages/payment_methods/payment_page/content.dart

@@ -1,12 +1,8 @@
 import 'package:flutter/material.dart';
 
-import 'package:provider/provider.dart';
-
-import 'package:pshared/models/payment/methods/data.dart';
+import 'package:pshared/models/payment/wallet.dart';
 import 'package:pshared/models/recipient/recipient.dart';
-import 'package:pshared/provider/recipient/pmethods.dart';
 import 'package:pshared/provider/recipient/provider.dart';
-import 'package:pshared/provider/payment/flow.dart';
 
 import 'package:pweb/pages/payment_methods/payment_page/back_button.dart';
 import 'package:pweb/pages/payment_methods/payment_page/header.dart';
@@ -26,8 +22,7 @@ class PaymentPageContent extends StatelessWidget {
   final ValueChanged<Recipient?>? onBack;
   final Recipient? recipient;
   final RecipientsProvider recipientProvider;
-  final PaymentMethodsProvider methodsProvider;
-  final MethodMap availablePaymentTypes;
+  final ValueChanged<Wallet> onWalletSelected;
   final PayoutDestination fallbackDestination;
   final TextEditingController searchController;
   final FocusNode searchFocusNode;
@@ -41,8 +36,7 @@ class PaymentPageContent extends StatelessWidget {
     required this.onBack,
     required this.recipient,
     required this.recipientProvider,
-    required this.methodsProvider,
-    required this.availablePaymentTypes,
+    required this.onWalletSelected,
     required this.fallbackDestination,
     required this.searchController,
     required this.searchFocusNode,
@@ -55,7 +49,6 @@ class PaymentPageContent extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final dimensions = AppDimensions();
-    final flowProvider = context.watch<PaymentFlowProvider>();
     final loc = AppLocalizations.of(context)!;
 
     return Align(
@@ -84,7 +77,7 @@ class PaymentPageContent extends StatelessWidget {
                   SectionTitle(loc.sourceOfFunds),
                   SizedBox(height: dimensions.paddingSmall),
                   PaymentMethodSelector(
-                    onMethodChanged: (m) => methodsProvider.setCurrentObject(m.id),
+                    onMethodChanged: onWalletSelected,
                   ),
                   SizedBox(height: dimensions.paddingXLarge),
                   RecipientSection(
@@ -98,12 +91,7 @@ class PaymentPageContent extends StatelessWidget {
                     onRecipientCleared: onRecipientCleared,
                   ),
                   SizedBox(height: dimensions.paddingXLarge),
-                  PaymentInfoSection(
-                    dimensions: dimensions,
-                    flowProvider: flowProvider,
-                    recipient: recipient,
-                    availableTypes: availablePaymentTypes,
-                  ),
+                  PaymentInfoSection(dimensions: dimensions),
                   SizedBox(height: dimensions.paddingLarge),
                   const PaymentFormWidget(),
                   SizedBox(height: dimensions.paddingXXXLarge),

frontend/pweb/lib/pages/payment_methods/payment_page/method_selector.dart

@@ -17,9 +17,11 @@ class PaymentMethodSelector extends StatelessWidget {
   });
 
   @override
-  Widget build(BuildContext context) => Consumer<WalletsProvider>(builder:(context, provider, _) =>  PaymentMethodDropdown(
-    methods: provider.wallets,
-    initialValue: provider.selectedWallet,
-    onChanged: onMethodChanged,
-  ));
+  Widget build(BuildContext context) => Consumer<WalletsProvider>(
+        builder: (context, provider, _) => PaymentMethodDropdown(
+          methods: provider.wallets,
+          selectedMethod: provider.selectedWallet,
+          onChanged: onMethodChanged,
+        ),
+      );
 }

frontend/pweb/lib/pages/payment_methods/payment_page/page.dart

@@ -1,12 +1,8 @@
 import 'package:flutter/material.dart';
 
-import 'package:provider/provider.dart';
-
-import 'package:pshared/models/payment/methods/data.dart';
+import 'package:pshared/models/payment/wallet.dart';
 import 'package:pshared/models/recipient/recipient.dart';
-import 'package:pshared/provider/recipient/pmethods.dart';
 import 'package:pshared/provider/recipient/provider.dart';
-import 'package:pshared/provider/payment/flow.dart';
 
 import 'package:pweb/pages/dashboard/payouts/widget.dart';
 import 'package:pweb/pages/payment_methods/payment_page/back_button.dart';
@@ -26,8 +22,7 @@ class PaymentPageContent extends StatelessWidget {
   final ValueChanged<Recipient?>? onBack;
   final Recipient? recipient;
   final RecipientsProvider recipientProvider;
-  final PaymentMethodsProvider methodsProvider;
-  final MethodMap availablePaymentTypes;
+  final ValueChanged<Wallet> onWalletSelected;
   final PayoutDestination fallbackDestination;
   final TextEditingController searchController;
   final FocusNode searchFocusNode;
@@ -41,8 +36,7 @@ class PaymentPageContent extends StatelessWidget {
     required this.onBack,
     required this.recipient,
     required this.recipientProvider,
-    required this.methodsProvider,
-    required this.availablePaymentTypes,
+    required this.onWalletSelected,
     required this.fallbackDestination,
     required this.searchController,
     required this.searchFocusNode,
@@ -55,7 +49,6 @@ class PaymentPageContent extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final dimensions = AppDimensions();
-    final flowProvider = context.watch<PaymentFlowProvider>();
     final loc = AppLocalizations.of(context)!;
 
     return Align(
@@ -84,7 +77,7 @@ class PaymentPageContent extends StatelessWidget {
                   SectionTitle(loc.sourceOfFunds),
                   SizedBox(height: dimensions.paddingSmall),
                   PaymentMethodSelector(
-                    onMethodChanged: (m) => methodsProvider.setCurrentObject(m.id),
+                    onMethodChanged: onWalletSelected,
                   ),
                   SizedBox(height: dimensions.paddingXLarge),
                   RecipientSection(
@@ -98,12 +91,7 @@ class PaymentPageContent extends StatelessWidget {
                     onRecipientCleared: onRecipientCleared,
                   ),
                   SizedBox(height: dimensions.paddingXLarge),
-                  PaymentInfoSection(
-                    dimensions: dimensions,
-                    flowProvider: flowProvider,
-                    recipient: recipient,
-                    availableTypes: availablePaymentTypes,
-                  ),
+                  PaymentInfoSection(dimensions: dimensions),
                   SizedBox(height: dimensions.paddingLarge),
                   const PaymentFromWrappingWidget(),
                   SizedBox(height: dimensions.paddingXXXLarge),

frontend/pweb/lib/pages/payment_methods/widgets/payment_info_section.dart

@@ -1,8 +1,8 @@
 import 'package:flutter/material.dart';
 
+import 'package:provider/provider.dart';
+
 import 'package:pshared/models/payment/methods/data.dart';
-import 'package:pshared/models/payment/type.dart';
-import 'package:pshared/models/recipient/recipient.dart';
 import 'package:pshared/provider/payment/flow.dart';
 
 import 'package:pweb/pages/payment_methods/form.dart';
@@ -15,25 +15,18 @@ import 'package:pweb/generated/i18n/app_localizations.dart';
 
 class PaymentInfoSection extends StatelessWidget {
   final AppDimensions dimensions;
-  final MethodMap availableTypes;
-  final PaymentFlowProvider flowProvider;
-  final Recipient? recipient;
 
   const PaymentInfoSection({
     super.key,
     required this.dimensions,
-    required this.availableTypes,
-    required this.flowProvider,
-    required this.recipient,
   });
 
   @override
   Widget build(BuildContext context) {
     final loc = AppLocalizations.of(context)!;
-    final hasRecipient = recipient != null;
-    final MethodMap resolvedAvailableTypes = hasRecipient
-        ? availableTypes
-        : {for (final type in PaymentType.values) type: null};
+    final flowProvider = context.watch<PaymentFlowProvider>();
+    final hasRecipient = flowProvider.hasRecipient;
+    final MethodMap resolvedAvailableTypes = flowProvider.availableTypes;
 
     if (hasRecipient && resolvedAvailableTypes.isEmpty) {
       return Text(loc.recipientNoPaymentDetails);
@@ -62,7 +55,7 @@ class PaymentInfoSection extends StatelessWidget {
               flowProvider.setManualPaymentData(data);
             }
           },
-          initialData: hasRecipient ? resolvedAvailableTypes[selectedType] : flowProvider.manualPaymentData,
+          initialData: flowProvider.selectedPaymentData,
           isEditable: !hasRecipient,
         ),
       ],

frontend/pweb/lib/pages/payment_methods/widgets/recipient_section.dart

@@ -45,25 +45,44 @@ class RecipientSection extends StatelessWidget {
       );
     }
 
-    return Column(
-      crossAxisAlignment: CrossAxisAlignment.start,
-      children: [
-        SectionTitle(loc.recipient),
-        SizedBox(height: dimensions.paddingSmall),
-        RecipientSearchField(
-          controller: searchController,
-          onChanged: onSearchChanged,
-          focusNode: searchFocusNode,
-        ),
-        if (recipientProvider.query.isNotEmpty) ...[
-          SizedBox(height: dimensions.paddingMedium),
-          RecipientSearchResults(
-            dimensions: dimensions,
-            recipientProvider: recipientProvider,
-            onRecipientSelected: onRecipientSelected,
-          ),
-        ],
-      ],
+    return AnimatedBuilder(
+      animation: recipientProvider,
+      builder: (context, _) {
+        final previousRecipient = recipientProvider.previousRecipient;
+        final hasQuery = recipientProvider.query.isNotEmpty;
+
+        return Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            SectionTitle(loc.recipient),
+            SizedBox(height: dimensions.paddingSmall),
+            RecipientSearchField(
+              controller: searchController,
+              onChanged: onSearchChanged,
+              focusNode: searchFocusNode,
+            ),
+            if (previousRecipient != null) ...[
+              SizedBox(height: dimensions.paddingSmall),
+              ListTile(
+                dense: true,
+                contentPadding: EdgeInsets.zero,
+                leading: const Icon(Icons.undo),
+                title: Text(loc.back),
+                subtitle: Text(previousRecipient.name),
+                onTap: () => onRecipientSelected(previousRecipient),
+              ),
+            ],
+            if (hasQuery) ...[
+              SizedBox(height: dimensions.paddingMedium),
+              RecipientSearchResults(
+                dimensions: dimensions,
+                recipientProvider: recipientProvider,
+                onRecipientSelected: onRecipientSelected,
+              ),
+            ],
+          ],
+        );
+      },
     );
   }
-}
+}

frontend/pweb/lib/pages/payout_page/page.dart

@@ -3,8 +3,8 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 
 import 'package:pshared/provider/recipient/pmethods.dart';
-
 import 'package:pshared/models/payment/wallet.dart';
+
 import 'package:pweb/pages/payout_page/methods/widget.dart';
 import 'package:pweb/pages/payout_page/wallet/wigets.dart';
 

frontend/pweb/lib/pages/payout_page/wallet/card.dart

@@ -3,11 +3,11 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 
 import 'package:pshared/utils/currency.dart';
-
 import 'package:pshared/models/payment/wallet.dart';
-import 'package:pweb/pages/dashboard/buttons/balance/amount.dart';
 import 'package:pshared/provider/payment/wallets.dart';
 
+import 'package:pweb/pages/dashboard/buttons/balance/amount.dart';
+
 import 'package:pweb/generated/i18n/app_localizations.dart';
 
 

frontend/pweb/lib/pages/payout_page/wallet/edit/buttons/send.dart

@@ -3,9 +3,9 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 
 import 'package:pshared/models/payment/type.dart';
+import 'package:pshared/provider/payment/wallets.dart';
 
 import 'package:pweb/app/router/payout_routes.dart';
-import 'package:pshared/provider/payment/wallets.dart';
 import 'package:pweb/widgets/sidebar/destinations.dart';
 
 import 'package:pweb/generated/i18n/app_localizations.dart';

frontend/pweb/lib/pages/payout_page/wallet/edit/buttons/top_up.dart

@@ -2,8 +2,9 @@ import 'package:flutter/material.dart';
 
 import 'package:provider/provider.dart';
 
-import 'package:pweb/app/router/payout_routes.dart';
 import 'package:pshared/provider/payment/wallets.dart';
+
+import 'package:pweb/app/router/payout_routes.dart';
 import 'package:pweb/widgets/sidebar/destinations.dart';
 
 import 'package:pweb/generated/i18n/app_localizations.dart';

frontend/pweb/lib/pages/payout_page/wallet/edit/fields.dart

@@ -3,9 +3,10 @@ import 'package:flutter/services.dart';
 
 import 'package:provider/provider.dart';
 
-import 'package:pweb/pages/dashboard/buttons/balance/amount.dart';
 import 'package:pshared/provider/payment/wallets.dart';
 
+import 'package:pweb/pages/dashboard/buttons/balance/amount.dart';
+
 
 class WalletEditFields extends StatelessWidget {
   const WalletEditFields({super.key});

frontend/pweb/lib/pages/payout_page/wallet/edit/page.dart

@@ -2,11 +2,12 @@ import 'package:flutter/material.dart';
 
 import 'package:provider/provider.dart';
 
+import 'package:pshared/provider/payment/wallets.dart';
+
 import 'package:pweb/pages/payout_page/wallet/edit/buttons/buttons.dart';
 import 'package:pweb/pages/payout_page/wallet/edit/fields.dart';
 import 'package:pweb/pages/payout_page/wallet/edit/header.dart';
 import 'package:pweb/pages/payout_page/wallet/history/history.dart';
-import 'package:pshared/provider/payment/wallets.dart';
 import 'package:pweb/utils/dimensions.dart';
 
 import 'package:pweb/generated/i18n/app_localizations.dart';

frontend/pweb/lib/pages/payout_page/wallet/history/history.dart

@@ -3,6 +3,7 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 
 import 'package:pshared/models/payment/wallet.dart';
+
 import 'package:pweb/pages/payout_page/wallet/history/filters.dart';
 import 'package:pweb/pages/payout_page/wallet/history/table.dart';
 import 'package:pweb/providers/wallet_transactions.dart';

frontend/pweb/lib/pages/payout_page/wallet/wigets.dart

@@ -3,9 +3,10 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 
 import 'package:pshared/models/payment/wallet.dart';
-import 'package:pweb/pages/payout_page/wallet/card.dart';
 import 'package:pshared/provider/payment/wallets.dart';
 
+import 'package:pweb/pages/payout_page/wallet/card.dart';
+
 
 class WalletWidgets extends StatelessWidget {
   final void Function(Wallet) onWalletTap;

frontend/pweb/lib/pages/wallet_top_up/content.dart

@@ -3,8 +3,8 @@ import 'package:flutter/material.dart';
 import 'package:pshared/models/payment/chain_network.dart';
 import 'package:pshared/utils/currency.dart';
 import 'package:pshared/utils/l10n/chain.dart';
-
 import 'package:pshared/models/payment/wallet.dart';
+
 import 'package:pweb/pages/wallet_top_up/details.dart';
 import 'package:pweb/pages/wallet_top_up/header.dart';
 import 'package:pweb/pages/wallet_top_up/meta.dart';

frontend/pweb/lib/pages/wallet_top_up/page.dart

@@ -2,9 +2,10 @@ import 'package:flutter/material.dart';
 
 import 'package:provider/provider.dart';
 
-import 'package:pweb/pages/wallet_top_up/content.dart';
 import 'package:pshared/provider/payment/wallets.dart';
 
+import 'package:pweb/pages/wallet_top_up/content.dart';
+
 import 'package:pweb/generated/i18n/app_localizations.dart';
 
 

frontend/pweb/lib/services/amplitude.dart

@@ -1,210 +0,0 @@
-import 'package:amplitude_flutter/amplitude.dart';
-import 'package:amplitude_flutter/configuration.dart';
-import 'package:amplitude_flutter/constants.dart' as amp;
-import 'package:amplitude_flutter/events/base_event.dart';
-import 'package:flutter/widgets.dart';
-import 'package:pshared/models/account/account.dart';
-import 'package:pshared/models/payment/type.dart';
-import 'package:pshared/models/recipient/status.dart';
-import 'package:pshared/models/recipient/type.dart';
-import 'package:pweb/widgets/sidebar/destinations.dart';
-
-
-class AmplitudeService {
-  static late Amplitude _analytics;
-
-  static Amplitude _amp() => _analytics;
-
-  static Future<void> initialize() async {
-    _analytics = Amplitude(Configuration(
-      apiKey: '12345', //TODO define through App Contants
-      serverZone: amp.ServerZone.eu, //TODO define through App Contants
-    ));
-    await _analytics.isBuilt;
-  }
-
-  static Future<void> identify(Account account) async =>
-      _amp().setUserId(account.id);
-
-  
-  static Future<void> login(Account account) async =>
-      _logEvent(
-        'login',
-        userProperties: {
-          // 'email': account.email, TODO Add email into account
-          'locale': account.locale,
-        },
-      );
-
-  static Future<void> logout() async => _logEvent("logout");
-
-  static Future<void> pageOpened(PayoutDestination page, {String? path, String? uiSource}) async {
-    return _logEvent("pageOpened", eventProperties: {
-      "page": page,
-      if (path != null) "path": path,
-      if (uiSource != null) "uiSource": uiSource,
-    });
-  }
-
-  //TODO Add when registration is ready. User properties {user_id, registration_date, has_wallet (true/false), wallet_balance (should concider loggin it as: 0 / <100 / 100–500 / 500+), preferred_method (Wallet/Card/Bank/IBAN), total_transactions, total_amount, last_payout_date, last_login_date , marketing_source}
-  
-  // static Future<void> registrationStarted(String method, String country) async =>
-  //   _logEvent("registrationStarted", eventProperties: {"method": method, "country": country});
-
-  // static Future<void> registrationCompleted(String method, String country) async =>
-  //     _logEvent("registrationCompleted", eventProperties: {"method": method, "country": country});
-
-  static Future<void> pageNotFound(String url) async =>
-      _logEvent("pageNotFound", eventProperties: {"url": url});
-
-  static Future<void> localeChanged(Locale locale) async =>
-      _logEvent("localeChanged", eventProperties: {"locale": locale.toString()});
-
-  static Future<void> localeMatched(String locale, bool haveRequested) async => //DO we need it?
-      _logEvent("localeMatched", eventProperties: {
-        "locale": locale,
-        "have_requested_locale": haveRequested
-      });
-
-  static Future<void> recipientAddStarted() async =>
-      _logEvent("recipientAddStarted");
-
-  static Future<void> recipientAddCompleted(
-    RecipientType type, 
-    RecipientStatus status, 
-    Set<PaymentType> methods,
-  ) async {
-    _logEvent(
-      "recipientAddCompleted", 
-      eventProperties: {
-        "methods": methods.map((m) => m.name).toList(),
-        "type": type.name,
-        "status": status.name,
-      },
-    );
-  }
-
-  static Future<void> _paymentEvent(
-    String evt,
-    double amount,
-    double fee,
-    bool payerCoversFee,
-    PaymentType source,
-    PaymentType recpientPaymentMethod, {
-    String? message,
-    String? errorType,
-    Map<String, dynamic>? extraProps,
-  }) async {
-    final props = {
-      "amount": amount,
-      "fee": fee,
-      "feeCoveredBy": payerCoversFee ? 'payer' : 'recipient',
-      "source": source,
-      "recipient_method": recpientPaymentMethod,
-      if (message != null) "message": message,
-      if (errorType != null) "error_type": errorType,
-      if (extraProps != null) ...extraProps,
-    };
-    return _logEvent(evt, eventProperties: props);
-  }
-
-  static Future<void> paymentPrepared(double amount, double fee,
-          bool payerCoversFee, PaymentType source, PaymentType recpientPaymentMethod) async =>
-      _paymentEvent("paymentPrepared", amount, fee, payerCoversFee, source, recpientPaymentMethod);
-  //TODO Rework paymentStarted (do i need all those properties or is the event enough? Mb properties should be passed at paymentPrepared)
-  static Future<void> paymentStarted(double amount, double fee,
-          bool payerCoversFee, PaymentType source, PaymentType recpientPaymentMethod) async =>
-      _paymentEvent("paymentStarted", amount, fee, payerCoversFee, source, recpientPaymentMethod);
-
-  static Future<void> paymentFailed(double amount, double fee, bool payerCoversFee,
-      PaymentType source, PaymentType recpientPaymentMethod, String errorType, String message) async =>
-      _paymentEvent("paymentFailed", amount, fee, payerCoversFee, source, recpientPaymentMethod,
-          errorType: errorType, message: message);
-
-  static Future<void> paymentError(double amount, double fee, bool payerCoversFee,
-      PaymentType source,PaymentType recpientPaymentMethod, String message) async =>
-      _paymentEvent("paymentError", amount, fee, payerCoversFee, source, recpientPaymentMethod,
-          message: message);
-
-  static Future<void> paymentSuccess({
-    required double amount,
-    required double fee,
-    required bool payerCoversFee,
-    required PaymentType source, 
-    required PaymentType recpientPaymentMethod,
-    required String transactionId,
-    String? comment,
-    required int durationMs,
-  }) async {
-    return _paymentEvent(
-      "paymentSuccess",
-      amount,
-      fee,
-      payerCoversFee,
-      source,
-      recpientPaymentMethod,
-      message: comment,
-      extraProps: {
-        "transaction_id": transactionId,
-        "duration_ms": durationMs, //How do i calculate duration here?
-        "\$revenue": amount, //How do i calculate revenue here?
-        "\$revenueType": "payment", //Do we need to get revenue type?
-      },
-    );
-  }
-
-  //TODO add when support is ready
-  // static Future<void> supportOpened(String fromPage, String trigger) async =>
-  //     _logEvent("supportOpened", eventProperties: {"from_page": fromPage, "trigger": trigger});
-
-  // static Future<void> supportMessageSent(String category, bool resolved) async =>
-  //     _logEvent("supportMessageSent", eventProperties: {"category": category, "resolved": resolved});
-
-
-  static Future<void> walletTopUp(double amount, PaymentType method) async =>
-      _logEvent("walletTopUp", eventProperties: {"amount": amount, "method": method});
-
-
-  //TODO Decide do we need uiElementClicked or pageOpened is enough?
-  static Future<void> uiElementClicked(String elementName, String page, String uiSource) async =>
-      _logEvent("uiElementClicked", eventProperties: {
-        "element_name": elementName,
-        "page": page,
-        "uiSource": uiSource
-      });
-
-  static final Map<String, int> _stepStartTimes = {};
-  //TODO Consider it as part of payment flow or registration flow or adding recipient and rework accordingly
-  static Future<void> stepStarted(String stepName, {String? context}) async {
-    _stepStartTimes[stepName] = DateTime.now().millisecondsSinceEpoch;
-    return _logEvent("stepStarted", eventProperties: {
-      "step_name": stepName,
-      if (context != null) "context": context,
-    });
-  }
-
-  static Future<void> stepCompleted(String stepName, bool success) async {
-    final now = DateTime.now().millisecondsSinceEpoch;
-    final start = _stepStartTimes[stepName] ?? now;
-    final duration = now - start;
-    return _logEvent("stepCompleted", eventProperties: {
-      "step_name": stepName,
-      "duration_ms": duration,
-      "success": success
-    });
-  }
-
-  static Future<void> _logEvent(
-    String eventType, {
-    Map<String, dynamic>? eventProperties,
-    Map<String, dynamic>? userProperties,
-  }) async {
-    final event = BaseEvent(
-      eventType,
-      eventProperties: eventProperties,
-      userProperties: userProperties,
-    );
-    _amp().track(event);
-    print(event.toString()); //TODO delete when everything is ready
-  }
-}

frontend/pweb/lib/utils/payment/dropdown.dart

@@ -8,40 +8,27 @@ import 'package:pweb/pages/payment_methods/icon.dart';
 import 'package:pweb/generated/i18n/app_localizations.dart';
 
 
-class PaymentMethodDropdown extends StatefulWidget {
+class PaymentMethodDropdown extends StatelessWidget {
   final List<Wallet> methods;
   final ValueChanged<Wallet> onChanged;
-  final Wallet? initialValue;
+  final Wallet? selectedMethod;
 
   const PaymentMethodDropdown({
     super.key,
     required this.methods,
     required this.onChanged,
-    this.initialValue,
+    this.selectedMethod,
   });
 
-  @override
-  State<PaymentMethodDropdown> createState() => _PaymentMethodDropdownState();
-}
-
-class _PaymentMethodDropdownState extends State<PaymentMethodDropdown> {
-  late Wallet _selectedMethod;
-
-  @override
-  void initState() {
-    super.initState();
-    _selectedMethod = widget.initialValue ?? widget.methods.first;
-  }
-
   @override
   Widget build(BuildContext context) => DropdownButtonFormField<Wallet>(
     dropdownColor: Theme.of(context).colorScheme.onSecondary,
-    initialValue: _selectedMethod,
+    value: _getSelectedMethod(),
     decoration: InputDecoration(
       labelText: AppLocalizations.of(context)!.whereGetMoney,
       border: OutlineInputBorder(borderRadius: BorderRadius.circular(8)),
     ),
-    items: widget.methods.map((method) => DropdownMenuItem<Wallet>(
+    items: methods.map((method) => DropdownMenuItem<Wallet>(
       value: method,
       child: Row(
         children: [
@@ -53,9 +40,14 @@ class _PaymentMethodDropdownState extends State<PaymentMethodDropdown> {
     )).toList(),
     onChanged: (value) {
       if (value != null) {
-        setState(() => _selectedMethod = value);
-        widget.onChanged(value);
+        onChanged(value);
       }
     },
   );
-}
+
+  Wallet? _getSelectedMethod() {
+    if (selectedMethod != null) return selectedMethod;
+    if (methods.isEmpty) return null;
+    return methods.first;
+  }
+}