useTopUp
Fund the payment purse from a product account or provided keys
useTopUp moves funds into the app's RFC-0006 payment purse. Call
topUp(amount, source, into?); the promise resolves once the host has
performed the top-up. There is no return value to inspect: watch
usePaymentBalance to see the new
funds land.
source is a PaymentTopUpSource, a tagged union naming where the funds
come from: "ProductAccount" (one of the product's scoped accounts, by
derivationIndex), "PrivateKey" (a one-time account by its sr25519 secret
key) or "Coins" (coin secret keys, one per coin).
Payments are host-only: standalone the call rejects with
HostUnavailableError.
Usage
import { useTopUp } from "@use-truapi/react";
function TopUpButton({ amount }: { amount: bigint }) {
const { topUp, isPending, isSuccess, error } = useTopUp();
function onTopUp() {
void topUp(amount, {
tag: "ProductAccount",
value: { derivationIndex: 0 },
}).catch(() => {});
}
return (
<>
<button type="button" onClick={onTopUp} disabled={isPending}>
{isPending ? "Topping up…" : "Top up"}
</button>
{isSuccess && <p>Purse funded ✓</p>}
{error && <p role="alert">{error.message}</p>}
</>
);
}<script setup lang="ts">
import { useTopUp } from "@use-truapi/vue";
const props = defineProps<{ amount: bigint }>();
const { topUp, isPending, isSuccess, error } = useTopUp();
function onTopUp() {
void topUp(props.amount, {
tag: "ProductAccount",
value: { derivationIndex: 0 },
}).catch(() => {});
}
</script>
<template>
<button type="button" :disabled="isPending" @click="onTopUp">
{{ isPending ? "Topping up…" : "Top up" }}
</button>
<p v-if="isSuccess">Purse funded ✓</p>
<p v-if="error" role="alert">{{ error.message }}</p>
</template>The handlers above are fire-and-forget: the empty catch silences the
rejected promise, and the failure still shows up in error. To fund a
non-main purse, pass its PaymentPurseId as the third argument:
await topUp(amount, source, 1);See also
usePaymentBalancewatches the purse fill up.useRequestPaymentspends from the purse.
API reference
React
function useTopUp(options?): NamedMutation<void, TopUpVariables> & object;Top up the payment balance from a product account or provided keys: topUp(amount, source).
Parameters
| Parameter | Type |
|---|---|
options? | { mutation?: MutationOptions<void, TopUpVariables>; } |
options.mutation? | MutationOptions<void, TopUpVariables> |
Returns
NamedMutation<void, TopUpVariables> & object
Properties
amount
amount: bigint;into?
optional into?: number;source
source: PaymentTopUpSource;Vue
function useTopUp(options?): NamedMutation<void, TopUpVariables> & object;Top up the payment balance from a product account or provided keys: topUp(amount, source).
Parameters
| Parameter | Type |
|---|---|
options? | { mutation?: MutationOptions<void, TopUpVariables>; } |
options.mutation? | MutationOptions<void, TopUpVariables> |
Returns
NamedMutation<void, TopUpVariables> & object
Properties
amount
amount: bigint;into?
optional into?: number;source
source: PaymentTopUpSource;