Agent hello world

A "hello world" tour: get authority, point the agent at the skill (or install the SDK), make one paid call, verify the receipt.

This build is Sui testnet.

1. Get authority (once)

You need an owner-funded spend account and a scoped grant that names this agent's public Sui address.

1. Open the console (local: http://localhost:3000).
2. Sign in with a Sui wallet (personal message). There is no Sui Agent Payments buyer account.
3. Create and fund one spend account for the asset you will spend.
4. Authorize this agent — MCP consent in the browser, or register the public address the agent already generated.

Neither path puts a delegate secret on the platform. Full owner steps: Authorize an agent (BYO) or Pay with MCP (hosted).

You also need a paid resource URL from discovery:

GET /v1/services
GET /v1/services/{id}

Use resourceUrl from the catalog. Do not pay a raw seller upstream.

2. Fastest path — hand the agent the skill

Fetch https://suipay.dev/SKILL.md and follow it.

The skill walks discovery, the HTTP 402, paying, and verifying the receipt. A capable agent needs nothing else for the first paid call.

Also useful:

GET /llms.txt
GET /.well-known/mcp.json

3. Or install the SDK and pay in-process

pnpm add @cmdoss/suipay-buyer

The owner must already have registered this key's public address (step 1). Load the secret from your own store — never from this page.

// The whole agent path in one file: key, payer, paid call. Included by
// quickstart/agent-buyer.
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
import { createPayer } from '@cmdoss/suipay-buyer'
 
// In your process this comes from the agent secret store.
const keypair = Ed25519Keypair.fromSecretKey(new Uint8Array(32))
 
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/v1/image/generate',
  {
    method: 'POST',
    body: JSON.stringify({ prompt: 'A blue ceramic robot' }),
    contentType: 'application/json',
    intent: { asset: '0x...::usdc::USDC', maxAmount: '50000' },
  },
)
 
export { keypair, payer, result }

createPayer discovers the deployment, resolves the grants naming this key, and then reads the grant object itself with an unsigned getObject — refusing unless the chain agrees the grant names this delegate. It never asks for the gateway's HMAC secret.

intent is required. An offer outside it is refused before any ledger claim, build, or sign.

Full guide: Pay with the SDK. Raw HTTP without the helper: Pay with REST.

4. Or connect remote MCP

1. Resolve GET /.well-known/mcp.json (local: http://localhost:4340/mcp).
2. Complete OAuth in the browser. The agent presents the public address of the key it already holds.
3. Call access_context before spending. Match a discovered service by service ID, method, and path — not by a similar display name.
4. Call pay with the same URL, method, headers, and body you intend to use. The tool mints a fresh challenge, settles, and fetches the resource.
5. Call receipts and confirm challenge, network, amount, asset, payer, and a non-empty Sui digest.

Full guide: Pay with MCP.

5. Inspect the 402, then the receipt

Any unpaid call to the public gateway resource URL must return HTTP 402. Validate challenge ID, integer atomic amount, asset, recipient, sui:<network>, expiry, HTTP method, path, body binding when present, and service revision. Select only a dialect the response actually advertises. Spend-account resources currently advertise MPP pay-then-prove.

After payment, require a successful receipt (Payment-Receipt for MPP) with the expected challenge, network, amount, asset, payer, and a non-empty Sui transaction digest. Verify on Suiscan.

If a timeout, disconnect, or 5xx happens after payment begins, the outcome is ambiguous. Reconcile the challenge, receipt, digest, and chain state before creating another payment.