paybondpaybond
Sign in

T01 · Tutorial

First guarded spend (sandbox)

Log in, run the local dev loop, smoke a paid tool, open :9477 — sandbox first, no production rails.

~15 minIntroSandboxbuildercommercefast evalTerminal stages

Outcome: Complete authorize → execute → evidence offline or against sandbox Gateway.

Learning view: objectives and extras expanded. Switch for commands only.

Mental model

Kit control loop is authorize → execute → evidence. Sandbox proves the loop before any live rail.

You will be able to

  • Run paybond dev loop --offline and interpret a green smoke
  • Log in so tenant scope comes only from the API key
  • Open paybond dev trace and locate authorize vs evidence at :9477

Prerequisites

  • · Node 20+ or Python 3.11+ and a terminal in an empty project directory
  • · No production Stripe/Shopify setup required

What you'll build

Before adapters or commerce providers, prove Kit's control loop locally: authorize → execute → evidence. No production payment rails required for this tutorial.

Environment ready

3 min

You will

  • Install the Kit CLI entrypoint (npm/npx @paybond/kit)
  • Pick offline mock or sandbox credentials
  • Stay in one project directory for trace paths

Dev loop green

7 min

You will

  • See tool validation pass against policy
  • Complete a smoke with integer cents spend ceilings
  • Land a local .paybond/dev-trace.jsonl file

Timeline readable

5 min

You will

  • Open the vertical timeline at :9477
  • Identify authorize vs evidence vs settlement steps
  • Know where to go next: policy, middleware, or commerce lab

15-minute command stages

  1. Step 1 of 5

    Offline loop (no API key)

    Scaffold a travel policy, validate tools, and run authorize → evidence with an in-process mock.

    Goal: Prove the control loop on your laptop without credentials.

    Run this

    paybond dev loop --offline

    Example response

    ✓ policy scaffolded (travel preset)
✓ tools validated
✓ authorize → evidence ok
  wrote .paybond/dev-trace.jsonl

    You should see: Exit 0, paybond.policy.yaml present, .paybond/dev-trace.jsonl written.

    Note: Best first step with no sandbox key. Creates local policy and a trace file you can open later.

  2. Step 2 of 5

    Sandbox login

    Writes PAYBOND_API_KEY to .env.local (mode 0600). Tenant scope comes from the credential — never from agent args.

    Goal: Attach a real sandbox key so later stages hit Gateway, not only the mock.

    Run this

    npx -p @paybond/kit paybond login
# or: npm i -g @paybond/kit && paybond login

    Example response

    Logged in to sandbox.
Wrote .env.local (mode 0600).

    You should see: .env.local exists with PAYBOND_API_KEY.

    Note: Without a global install: npx -p @paybond/kit paybond login

  3. Step 3 of 5

    Real sandbox loop

    Same authorize → execute → evidence path against the Paybond sandbox Gateway after login.

    Goal: Same steps as offline, now on the network against sandbox.

    Run this

    paybond dev loop

    Example response

    ✓ authorize  travel.book_hotel  ≤ $200.00
✓ execute    ok
✓ evidence   cost_cents=18700
  captured $187.00 · released $13.00

    You should see: Smoke completes without spend_denied for the travel preset.

  4. Step 4 of 5

    Open local trace

    Second terminal, same project directory. Serves a timeline at http://127.0.0.1:9477 from .paybond/dev-trace.jsonl.

    Goal: Inspect the last smoke as a vertical timeline (CLI stays headless).

    Run this

    paybond dev trace

    Example response

    Trace UI listening on http://127.0.0.1:9477
Serving .paybond/dev-trace.jsonl

    You should see: Browser at :9477 shows authorize then evidence for your last smoke.

    Note: Hosted replay (no local server): /demo/agent-trace. dev loop records events; it does not start the dashboard.

  5. Step 5 of 5

    Manual middleware smoke (optional)

    Exercise one named operation with a spend ceiling and evidence body — useful when iterating a single tool.

    Goal: You choose the operation and cents ceiling — same boundary middleware uses later.

    Run this

    paybond agent sandbox smoke --operation travel.book_hotel --requested-spend-cents 20000 --evidence-preset cost_and_completion --result-body '{"status":"ok","cost_cents":18700}' --format json

    Example response

    {
  "authorized": true,
  "operation": "travel.book_hotel",
  "requested_spend_cents": 20000,
  "settled_cost_cents": 18700,
  "status": "released"
}

    You should see: JSON shows authorized spend and validated cost_cents (not spend_denied).

Guardrails to remember

  • Tenant identity is derived from the authenticated API key — never pass tenant IDs from unauthenticated agent args.
  • Spend uses integer cents (20000 = $200.00). cost_and_completion resizes settlement to validated evidence cost.
  • Recipes (Stripe/Shopify production smokes) live under Guides → Recipes — jump there only after sandbox is green.

Prefer a longer written walkthrough? See the Agent quickstart.

Verify before you continue

Check these off against your terminal or timeline output — progress stays on this device.

0/3

If something goes wrong

  • If you see

    Trace dashboard refuses connections

    Do this

    dev loop only records events. Start paybond dev trace in a second terminal in the same directory.

  • If you see

    Login works but tenant ID was passed in a tool arg

    Do this

    Drop tenant/intent from tool arguments — they are session-bound from credentials only.

  • If you see

    Spend looks like $200 instead of 20000 cents

    Do this

    Use integer cents (20000 = $200.00). Floating dollar amounts are not accepted.

Self-check

Answer without scrolling up — then reveal the model answer to compare.

In one sentence: why does offline mode still exercise the same authorize → evidence path as a sandbox key?

Next steps

Pick a branch — not every path needs every tutorial.

Related docs & recipes

Recipes are copy-paste production smokes — not repeated inside this tutorial.