Sui Charge Method

MPP uses HTTP 402 Payment Required to negotiate payments between clients and servers. The sui charge method implements this negotiation using USDC transfers on the Sui blockchain, providing sub-second finality and trustless verification.

Every MPP payment follows a four-step request-challenge-pay-verify cycle:

1. 1
   Request

   Client sends a standard HTTP request to the server endpoint.
2. 2
   Challenge (402)

   Server responds with 402 Payment Required and a WWW-Authenticate header containing the charge method, amount, currency, and recipient address.
3. 3
   Pay

   Client parses the challenge, builds a Sui transaction transferring the requested USDC amount to the recipient, executes it on-chain, and retries the original request with the transaction digest as a credential.
4. 4
   Verify & Deliver

   Server queries the Sui RPC, confirms the transaction succeeded, verifies the payment amount and recipient, then returns the API response.

When a server requires payment, it responds with 402 and a challenge encoded in the WWW-Authenticate header:

HTTP/1.1 402 Payment Required
WWW-Authenticate: MPP method="sui",
  amount="0.01",
  currency="0xdba346...::usdc::USDC",
  recipient="0xYOUR_SUI_ADDRESS"

After executing the on-chain payment, the client retries the request with the credential in the Authorization header:

Authorization: MPP method="sui", digest="<TX_DIGEST>"

The sui charge method is defined using the mppx Method schema:

import { Method, z } from 'mppx';

export const suiCharge = Method.from({
  intent: 'charge',
  name: 'sui',
  schema: {
    credential: {
      payload: z.object({
        digest: z.string(),
      }),
    },
    request: z.object({
      amount: z.string(),
      currency: z.string(),
      recipient: z.string(),
    }),
  },
});

When the server receives a credential, it performs four verification steps:

1. 1
   Fetch transaction

   Query the Sui RPC with getTransaction using the provided digest. Include balanceChanges in the response.
2. 2
   Check success

   Verify status.success === true. Reject failed or pending transactions.
3. 3
   Find payment

   Scan balanceChanges for an entry where:

   • • coinType matches the requested currency
   • • address matches the recipient (normalized)
   • • amount is positive (incoming transfer)
4. 4
   Check amount

   Convert the challenge amount to raw units using the currency's decimals (USDC = 6). Verify the transferred amount >= requested amount.

const tx = await client.getTransaction({ digest, include: { balanceChanges: true } });

if (!tx.status.success) throw new Error('Transaction failed');

const payment = tx.balanceChanges.find(
  (bc) =>
    bc.coinType === currency &&
    normalize(bc.address) === normalize(recipient) &&
    BigInt(bc.amount) > 0n,
);

if (!payment) throw new Error('Payment not found');

const transferredRaw = BigInt(payment.amount);
const requestedRaw = parseAmountToRaw(amount, 6); // USDC = 6 decimals
if (transferredRaw < requestedRaw) throw new Error('Underpaid');

When a client receives a 402 challenge, it builds and executes a Sui transaction:

import { Transaction, coinWithBalance } from '@mysten/sui/transactions';

const tx = new Transaction();
tx.setSender(walletAddress);

const amountRaw = parseAmountToRaw(challenge.amount, 6);
const payment = coinWithBalance({ balance: amountRaw, type: challenge.currency });
tx.transferObjects([payment], challenge.recipient);

const result = await client.signAndExecuteTransaction({ transaction: tx });
// Credential: { digest: result.digest }

The coinWithBalance helper automatically splits coins from the sender's balance. The transaction digest becomes the credential's proof of payment.

The canonical USDC coin type on Sui mainnet:

0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC

Amounts in challenges and credentials are human-readable strings (e.g. "0.01"). Both client and server must convert to raw units for on-chain operations:

function parseAmountToRaw(amount: string, decimals: number): bigint {
  const [whole = '0', frac = ''] = amount.split('.');
  const paddedFrac = frac.padEnd(decimals, '0').slice(0, decimals);
  return BigInt(whole + paddedFrac);
}

// Examples:
// parseAmountToRaw("0.01", 6)  → 10000n
// parseAmountToRaw("1",    6)  → 1000000n
// parseAmountToRaw("0.5",  6)  → 500000n

The official TypeScript implementation: