@cmdoss/suipay-buyer

Typed buyer SDK for SuiPay. Pay a 402 from a delegated spend-account grant, or manage the same /v1 control plane the console and MCP already use.

V1 allowance settlement is retired (HTTP 410). This package leads with createPayer over a spend-account grant.

Install

pnpm add @cmdoss/suipay-buyer

Do not publish or depend on @cmdoss/suipay-core. The wire types and 402 codec are bundled into this package.

Quickstart — pay

import { createPayer } from '@cmdoss/suipay-buyer';
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';

const keypair = Ed25519Keypair.fromSecretKey(/* 32-byte seed */);

const payer = await createPayer({
  gatewayUrl: 'https://gateway.example',
  keypair,
});
if (!payer.ok) throw new Error(payer.error.detail);
const result = await payer.value.pay('https://gateway.example/paid/weather', {
  intent: { maxAmount: '1000000', asset: '0x2::sui::SUI' },
});

Quickstart — connection card

The console Connection card is an AgentConnectionManifest. Parse it, then pay with the same barrel — do not import private src/agent-sdk/.

import {
  parseAgentManifest,
  manifestToSession,
  createReader,
  personalMessageSigner,
  type AgentConnectionManifest,
} from '@cmdoss/suipay-buyer';
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';

const parsed = parseAgentManifest(card as AgentConnectionManifest);
if (!parsed.ok) throw new Error(parsed.error.code);
const keypair = Ed25519Keypair.fromSecretKey(/* 32-byte seed */);
const session = manifestToSession({ manifest: parsed.value, signer: keypair });
if (!session.ok) throw new Error(session.error.code);

const reads = createReader({
  gatewayUrl: 'https://gateway.example',
  context: {
    network: session.value.session.network,
    packageId: session.value.session.packageId,
    grantObjectId: session.value.session.authority.grantObjectId,
    delegateAddress: session.value.session.authority.delegateAddress,
  },
  signPersonalMessage: personalMessageSigner(keypair),
});
await reads.balance();

Quickstart — control plane

createBuyer wraps /v1 only. It loads no node:sqlite and needs no native addons.

import { createBuyer } from '@cmdoss/suipay-buyer';

const client = createBuyer({
  baseUrl: 'https://gateway.example',
  getAuthorization: () => `Bearer ${sessionToken}`,
  ownerAddress: '0x…',
  signer: {
    address: '0x…',
    async signTransaction({ bytes }) {
      /* wallet or keypair over sponsored BCS bytes */
      return { signature: '…' };
    },
  },
});

const accounts = await client.accounts.list();
const created = await client.agents.createAndActivate({
  agentAddress: '0x…',
  name: 'my-agent',
  assetScopes: [
    {
      asset: 'sui',
      totalBudgetAtomic: '1000000000',
      maxPerPaymentAtomic: '10000000',
    },
  ],
  idempotencyKey: 'grant-1',
});

createAndActivate and the pool / policy / grant action helpers run the prepare → sponsor → sign → execute → finalize round-trip. After execute is sent, a lost confirmation is FINALITY_PENDING and is not retried.

Entries

| Import | What it is | | --- | --- | | @cmdoss/suipay-buyer | Delegated pay, createPayer, typed /v1 client | | @cmdoss/suipay-seller | requireProof (JWKS); createSeller on ./paid | | @cmdoss/suipay-mcp | MCP client |

A management-only import of the main entry needs no native addons.

Build (this repo)

pnpm --filter @cmdoss/suipay-buyer test
pnpm --filter @cmdoss/suipay-buyer build

Publishing to npm is an owner step. Do not run npm publish from CI.