Sending Payments

1. Check the balanceCopy Anchor Link

List wallet balances returns every wallet of a customer with its balances.

2. Get a quoteCopy Anchor Link

Get fee quote returns the network fee and the maximum amount the wallet can send. Do not send the sender's address: we find the wallet from moduleId and the x-customer-id header, and return the one we priced.

Amounts are in the asset's display unit, for example "12.5" USD₮ or "0.001" BTC, never in base units.

3. SendCopy Anchor Link

Every payment is approved with the customer's passkey. The flow depends on the network.

EVM (evm_erc4337)Copy Anchor Link

1. Prepare userOp with the chain, token, recipient and amount. It returns a userOpHash.
2. Have the customer sign the userOpHash with their passkey.
3. Submit userOp signature. The payment is broadcast once the wallet's signing threshold is met; for most wallets that is one signature.

Example: approving an EVM paymentCopy Anchor Link

In the browser, turn the userOpHash into the passkey challenge and ask the customer to approve:

import { startAuthentication } from '@simplewebauthn/browser';

function hashToChallenge(userOpHash: string) {
  const bytes = userOpHash
    .slice(2)
    .match(/../g)!
    .map(h => parseInt(h, 16));
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

const challenge = hashToChallenge(userOpHash);
const assertion = await startAuthentication({
  optionsJSON: {
    challenge,
    rpId: 'your-domain.com',
    allowCredentials: [{ id: credentialId, type: 'public-key' }],
    userVerification: 'required',
  },
});
await fetch('/payments/approve', {
  method: 'POST',
  body: JSON.stringify({ userOpHash, challenge, assertion }),
});

On your server, submit the signature:

await fetch(`https://api.pilot.shiga.io/v1/userops/${userOpHash}/signatures`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHIGA_API_KEY}`,
    'x-customer-id': customerId,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    passkeyPublicKey: { x: passkey.x, y: passkey.y },
    passkeyData: {
      credential: assertion,
      expectedChallenge: challenge,
      expectedOrigins: ['https://your-domain.com'],
      expectedRPID: 'your-domain.com',
      authenticator: {
        credentialId: passkey.credentialId,
        credentialPublicKey: passkey.credentialPublicKey,
        counter: 0,
      },
    },
  }),
});

passkeyPublicKey is the { x, y } returned when the wallets were provisioned. expectedChallenge must be the base64url encoding of the userOpHash bytes, not the hash as text.

Bitcoin, Spark, Solana, Tron and TONCopy Anchor Link

On these networks the wallet key is held in our signing enclave. The enclave signs only after it verifies the customer's passkey approval of the exact transfer. See How wallets are secured.

1. Choose a transactionId. Your own integer sequence number for this transfer. Keep it the same if you retry.
2. Build the challenge from the wallet's entityKey, its moduleId and the transfer details (below).
3. Have the customer approve with their passkey, using the challenge.
4. Submit with Submit transaction. We sign and broadcast in one step.

Transfer details (txParams)Copy Anchor Link

Building the challengeCopy Anchor Link

The challenge is the base64url SHA-256 of a canonical JSON object: keys sorted at every level, no spaces.

import { createHash } from 'node:crypto';

function canonical(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(canonical);
  if (value && typeof value === 'object') {
    return Object.fromEntries(
      Object.keys(value)
        .sort()
        .map(key => [key, canonical((value as Record<string, unknown>)[key])]),
    );
  }
  return value;
}

function transferChallenge(
  entityKey: string,
  moduleId: string,
  txParams: Record<string, unknown>,
) {
  const { selectedPayment, networkConfig, ...rest } = txParams;
  const asset = Object.fromEntries(
    Object.entries((networkConfig ?? {}) as Record<string, unknown>).filter(
      ([key]) => ['tokenMint', 'tokenRoot'].includes(key),
    ),
  );
  const intent =
    networkConfig === undefined ? rest : { ...rest, networkConfig: asset };
  return createHash('sha256')
    .update(
      JSON.stringify(canonical({ entityKey, moduleId, txParams: intent })),
    )
    .digest('base64url');
}

SubmittingCopy Anchor Link

Send moduleId, txParams and passkeyData: the customer's assertion (credential), the challenge as expectedChallenge, and the passkey's authenticator details. The response returns the transaction with status submitted.

On a treasury wallet that needs more than one approval, each signer submits the same transfer with their own passkey. Until enough have approved, the response carries awaitingApprovals; approvals lapse after 15 minutes.

A payment to the wallet's own address is refused with 400 validation_failed.

Payment statuses and eventsCopy Anchor Link

transaction.reconciled is the signing side's report of the same confirmation as transaction.success; act on transaction.success. transaction.summary_corrected corrects a past transaction's details and does not change its status.

Only confirmed means paid; see Reliability. Read payments with List transactions, or receive each change as a notification. See Notifications.

ErrorsCopy Anchor Link