Skip to content
WonderTwin docs

Your first twin

A WonderTwin Stripe twin doesn’t just return valid JSON. It tracks balances, creates transfers, fires webhooks, and maintains state across requests — like the real Stripe API. Built to pass compatibility tests against official SDKs.

So spinning one up and using it from your code is intentionally minimal. Three steps, no new framework.

  1. Declare

    Section titled “Declare”

    Configure the twins you want in a wondertwin.json at the root of your repo. Each twin gets a version, a localhost port, and (optional) seed fixtures.

    wondertwin.json
    {
      "twins": {
        "stripe": {
          "version": "0.3.2",
          "port": 4111,
          "seed": "./fixtures/stripe.json"
        },
        "twilio": {
          "version": "latest",
          "port": 4112
        },
        "clerk": {
          "version": "~0.2",
          "port": 4113
        }
      }
    }

  2. Activate

    Section titled “Activate”

    wt up reads wondertwin.json and launches every configured twin on its designated port:

    Terminal window
    wt up
    # ✓ stripe running on :4111
    # ✓ twilio running on :4112
    # ✓ clerk  running on :4113

    Each twin is a single Go binary, milliseconds to launch. They run as background processes on your laptop. wt status shows what’s up; wt down stops them.

  3. Point at localhost

    Section titled “Point at localhost”

    Change the base URL in your SDK’s configuration to target the local twin. Nothing else changes — same method names, same parameters, same responses.

    stripe.SetBackend(
      stripe.APIBackend,
      &stripe.BackendConfig{
        URL: "http://localhost:4111",
      },
    )
    

    // Everything else stays the same
    transfer, err := transfer.New(
      &stripe.TransferParams{
        Amount:   stripe.Int64(1000),
        Currency: stripe.String("usd"),
      },
    )

Your existing tests. Your existing SDK calls. Zero changes beyond the base URL.

What’s next

Section titled “What’s next”
  • Wire your application end-to-end — the full integration playbook: dev → staging → CI → production, including the bright line at prod (twins are never used in production).
  • Run twins in CI — make wt up part of your test pipeline; per-platform setups for GitHub Actions, GitLab CI, CircleCI.
  • Browse the catalog — every twin we offer.