salt-sdk - v0.0.45
    Preparing search index...

    Fees

    Some Salt operations incur a fee. Fees in Salt are paid using the x402 protocol. What the backend charges is named as a fee — getFeeTerms returns a FeeQuote — while paying it keeps x402's word, payment: payer, payment, signPayment and PaymentRequiredError.

    Operation Method
    Account creation createAccount
    Transaction submission submitTx

    Salt's SDK handles the x402 protocol end-to-end. You are in control of how users pay - x402 is flexible enough that the user can pay, or you can pay on their behalf.

    x402 is an open protocol that repurposes the HTTP 402 response to carry payment requirements in the response. Salt uses EIP-3009 signed messages to accept payments on chain.

    Pass payer (and optionally onPaymentRequired). The SDK makes the call (for example, submitting a transaction), gets a 402 response back from the server, signs against the terms it carries, and retries once.

    payer is a viem WalletClient, and the fee is paid on its chain (see Choosing a network), so create it on a chain it holds the token on. With a local key, that is all there is to it:

    import { createWalletClient, http } from 'viem';
    import { privateKeyToAccount } from 'viem/accounts';
    import { baseSepolia } from 'viem/chains';

    const payerWallet = createWalletClient({
    account: privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`),
    chain: baseSepolia, // one of the chainIds getFeeTerms quotes
    transport: http(),
    });

    const tx = await salt.submitTx({
    // ...account, value, chainId, walletClient, publicClient...
    payer: payerWallet,
    });

    onPaymentRequired is optional. It fires after the 402 arrives and the network has been chosen, before the signature is made, with the terms about to be signed. Throw from it to abort the payment.

    A browser wallet is where it earns its keep. The client's chain is the one it was created with, but the user can move their wallet to another chain afterwards, and a wallet refuses typed data whose domain names a chain it is not on. Switching to the chosen chain in onPaymentRequired puts it back:

    import { createWalletClient, custom } from 'viem';
    import { baseSepolia } from 'viem/chains';

    const [address] = await window.ethereum.request({
    method: 'eth_requestAccounts',
    });
    const payerWallet = createWalletClient({
    account: address,
    chain: baseSepolia,
    transport: custom(window.ethereum),
    });

    const tx = await salt.submitTx({
    // ...account, value, chainId, walletClient, publicClient...
    payer: payerWallet,
    onPaymentRequired: async ({ chainId, amount, asset }) => {
    console.log(`Paying ${amount} of ${asset} on chain ${chainId}`);
    if (chainId) await payerWallet.switchChain({ id: chainId });
    },
    });

    The SDK only asks for signTypedData and an account (and reads chain when there is one), so that is all payer is typed as — switching chains is the wallet's own business, and needs the full client. It only works for a wallet that can switch: a local key over http() cannot, which is why it is created on the right chain instead.

    Sometimes you will want to avoid the latency of a request, response, request again loop. In this situation you can check the price of your call using getFeeTerms, sign a payment with signPayment, then pass the result alongside your transaction or account creation call.

    const quote = await salt.getFeeTerms({ for: 'submitTx' });
    const option = quote.accepts.find((o) => o.chainId === payerWallet.chain.id);
    if (!option) throw new Error('Nothing quoted on the chain the payer is on');

    const payment = await salt.signPayment({ option, payer: payerWallet });

    const tx = await salt.submitTx({
    // ...account, value, chainId, walletClient, publicClient...
    payment,
    });

    Pass payment and payer. The pre-signed payment fires first. If the backend refuses it (for example because it expired), the reactive path kicks in automatically. It re-signs on the network the payer is on (see Choosing a network), which need not be the one the refused payment was on.

    const tx = await salt.submitTx({
    // ...account, value, chainId, walletClient, publicClient...
    payment,
    payer: payerWallet,
    onPaymentRequired: async ({ chainId }) => {
    if (chainId) await payerWallet.switchChain({ id: chainId });
    },
    });

    The backend accepts payment on several networks, and the payer must hold the token on the one it pays on. getFeeTerms is how you find out which networks those are: quote.accepts has one entry per network, each with its chainId, asset and amount.

    const quote = await salt.getFeeTerms({ for: 'submitTx' });
    const chainIds = quote.accepts.map((o) => o.chainId); // e.g. [421614, 84532]

    When pre-signing, you pick the option yourself — the one on the payer's chain:

    const option = quote.accepts.find((o) => o.chainId === payerWallet.chain.id);
    

    On the reactive path, the payer's chain picks: the SDK pays on the payer's chain if it is quoted, and otherwise on the first network quoted. A WalletClient carries the chain it was created with; for a Salt Account, pass chainId to accountAsPayer. So to pay on a given network, create the payer on it:

    import { baseSepolia } from 'viem/chains';

    const payerWallet = createWalletClient({
    account: privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`),
    chain: baseSepolia, // one of the chainIds getFeeTerms quotes
    transport: http(),
    });

    onPaymentRequired is told the network once it has been chosen. Switching the wallet from there doesn't change which network is paid on — switch to the chainId it hands you.

    Quotes can change — the price, and the networks on offer — so read them when you need them rather than holding one for the life of your app.

    • A viem WalletClient with an account attached (any wallet that can call signTypedData).
    • On the right chain — switch before calling signPayment, or in onPaymentRequired for the reactive path.
    • Holding the token (e.g. USDC) on that chain. The payer does not need to pay gas.

    The signer of the transaction (walletClient) and the payer of the payment (payer) do not need to be the same wallet. This makes it possible to, for example, pay for a transaction on a client's behalf.

    payer doesn't have to be a plain EOA wallet. accountAsPayer wraps an existing, funded Salt Account as a payer, so that account's own MPC key can cover another operation's x402 fee — useful for a treasury or sponsor account that pays on behalf of accounts it doesn't otherwise control.

    A Salt Account has the same address on every chain, so unlike a wallet it isn't "on" one. Tell accountAsPayer which chain the account holds the token on with chainId — one of the chainIds getFeeTerms quotes. Without it, the payment goes on the first network quoted.

    // Chains the treasury account holds USDC on, in order of preference.
    const fundedOn = [84532, 421614];

    const quote = await salt.getFeeTerms({ for: 'createAccount' });
    const chainId = fundedOn.find((id) =>
    quote.accepts.some((o) => o.chainId === id)
    );
    if (!chainId) throw new Error('The treasury is not funded on any quoted chain');

    // signer must be one of treasuryAccountId's own human signers, so it can
    // co-sign the payment on that account's behalf.
    const payer = await salt.accountAsPayer({
    accountId: treasuryAccountId,
    signer,
    chainId,
    });

    const ceremony = await salt.createAccount({
    // ...name, organisationId, signers, signer...
    payer,
    });

    The returned value slots into payer (or, pre-signed via signPayment, into payment) exactly like an EOA payer above — everything on this page about the two ways to pay still applies.

    Every payment the returned signer makes hosts a fresh signTypedData ceremony on the paying account, nested inside whatever operation it's paying for: the paying account's own signers and robos must be online to co-sign. To decouple that ceremony from the operation being paid for, pre-sign with signPayment and pass payment instead of payer.

    If that payment ceremony fails, the operation throws PaymentAuthorisationError, with the paying account's own error as its cause. See Error handling.

    PaymentRequiredError is thrown when a paid operation is called without a payer or payment, or when a payment is refused and there is no payer to re-sign with. It is a subclass of ApiError.

    To avoid it: pass payer, or pre-sign with getFeeTerms + signPayment + payment.

    To inspect it:

    import { PaymentRequiredError } from 'salt-sdk';

    try {
    const tx = await salt.submitTx({/* ... */});
    } catch (err) {
    if (err instanceof PaymentRequiredError) {
    console.log('Status:', err.status); // 402
    }
    throw err;
    }

    PaymentAuthorisationError is thrown when the payer itself fails to sign the payment: a wallet user rejects the signature, or, with accountAsPayer, the paying account's signing ceremony fails. The payment is signed before the paid-for request is sent, so nothing was created: no account record, no transaction proposal. Running the operation again is a clean retry.

    Whatever the payer threw is its cause. With accountAsPayer, that's an error from the paying account's ceremony, such as RoboStatusError when the paying account's robos are offline. It is the same type the operation's own ceremony could throw, which is why it arrives wrapped. Check for the wrapper first:

    import { PaymentAuthorisationError, RoboStatusError } from 'salt-sdk';

    try {
    const ceremony = await salt.createAccount({ /* ... */ payer });
    await ceremony.wait();
    } catch (err) {
    if (err instanceof PaymentAuthorisationError) {
    // The fee was never paid and no account was created.
    if (err.cause instanceof RoboStatusError) {
    console.log(
    `The paying account's robos are offline (payer ${err.payer})`
    );
    }
    } else if (err instanceof RoboStatusError) {
    // The new account's own robos.
    }
    throw err;
    }