Your first governed payment.

Go from a new workspace to an authorized sandbox payment with a scoped API, a TypeScript SDK, and an enforcing x402 integration.

1. Create your workspace and agent

Create an account, then create a workspace and register an agent. The initial policy allows the sample vendor at research.example, up to $2 per payment and $25/day. Amounts above $1 require review.

2. Create separate credentials

Open Developers. Create an agent credential for proposing and reading intents, and an executor credential for consuming grants. Keep the executor credential in your trusted integration process, outside the agent runtime.

3. Run the local example

The SDK is in packages/sdk. Build it with pnpm exec tsc -p packages/sdk/tsconfig.json, then install that local directory in your application. It is not yet published to npm.

# In the Wallito repository; set secrets in your shell environment
export WALLITO_URL=http://localhost:3000
export WALLITO_AGENT_KEY='your-agent-credential'
export WALLITO_EXECUTOR_KEY='your-executor-credential'
pnpm example

The example completes a small simulated payment, rejects a request over the hard limit, then waits while you approve a larger request in the dashboard. All requests go through the actual policy engine.

4. Integrate the SDK

import { Wallito } from '@wallito/sdk';

const agent = new Wallito({
  apiKey: process.env.WALLITO_AGENT_KEY!,
  baseURL: 'http://localhost:3000',
});

const decision = await agent.createIntent(payment, crypto.randomUUID());
if (decision.state === 'APPROVAL_REQUIRED') {
  const reviewed = await agent.waitForApproval(decision.id);
  // Continue only when reviewed.state === 'AUTHORIZED'.
}

Use normalizeX402 from packages/integrations/x402.ts to produce the payment object from the official x402 challenge. At execution, the trusted executor consumes the grant bound to that exact object. Never use freeform model text as permission.

API reference

Amounts and policy precedence

Amounts are integer strings of USDC atomic units. 100000 means $0.10 in the sandbox’s nominal USDC-to-USD accounting. One USDC has 1,000,000 atomic units. Arbitrary tokens, networks, negative amounts, exponent notation, and floating-point numbers are rejected. This nominal convention is not a market valuation or redemption guarantee.

Precedence: suspension → subscription access → mechanism → blocked vendor → allowed origin and recipient → hard per-payment limit → daily, monthly, lifetime, and workspace budgets → approval threshold. A human cannot override a hard prohibition.

Retries, grants, and interruptions

Reuse the same idempotency key after a timeout. A different payment with the same key returns 409. Grants are single-use and valid for 60 seconds. Pending approvals expire after 15 minutes. Policy changes or credential revocation can invalidate a grant. Submitted and uncertain payments retain their reservation across calendar boundaries.

Integration status

• x402: official v2 challenge parser, policy authorization, separate grant consumption, and simulated completion.
• MPP: official mppx challenge parser and reproducible inspection demo. Execution is denied.
• Stripe: test-mode checkout, portal, signed webhooks, and entitlements; requires your test account and prices.
• Privy, mainnet signing, verified on-chain settlement, Python SDK: planned.

Security boundaries

There is no unrestricted URL proxy. The integration parses a supplied response without forwarding credentials to arbitrary resources. Live payment execution is intentionally unavailable. Enable it only after implementing independent settlement verification, testing signer isolation, and completing security and regulatory review.