Build your first integration in 5 minutes

This walkthrough takes you from "no Wren account" to "first paid carbon offset via the API" in five minutes. We'll do it twice — once in test mode (safe, no charges) and once in live mode (real charge, real offset).

1. Sign up for an API team

Head to wren.co/wren-api and click Get an API key. The signup flow creates an API team — a shared workspace that owns the API token, the credit balance, and the billing relationship. Add a payment method when prompted (Stripe will only charge it when you top up credits or when an auto-refill triggers).

Once the team is created, head to Settings → Team → API & Credits.

2. Generate your test token

Click Generate test token. The token format is wren_test_<UUID> — copy it and keep it handy.

Test tokens authenticate the team for sandbox requests: realistic canned responses, no charges, no real offsets, no notifications. Safe to share with teammates and embed in code samples.

3. Make your first sandbox call

The "test": true flag and test_oo_ ID prefix confirm you hit the sandbox. Validation still ran — try omitting tons and you'll get a real 400.

4. Top up real credits

Back in API & Credits settings, enter an amount under Add Credits and confirm. Your team's payment method is charged once; the balance lands in the wallet.

We recommend starting with $20 — covers roughly 0.85 tons of offset, enough to validate a couple of live calls before committing to higher volumes.

5. Make your first live call

Generate or reveal your live token (also on the API & Credits page) and swap the auth header:

No "test": true flag — that's a real offset. Hold onto the id (it's your order_group_id) — you can fetch the certificate at GET /api/offset-orders/certificate/by-group/{id}.

What's next

• Offset Orders — full reference for /api/offset-orders (one-time, by-tonnage)
• Project Orders — fund a specific project directly
• Tree Orders — plant trees instead of offsetting
• Credits — wallet operations: balance, ledger, top-up, auto-refill
• Portfolios — list of available portfolios with their projects

Troubleshooting

401 Unauthorized with a fresh token — confirm you copied the full token (UUIDs are 36 chars; test tokens are wren_test_ + 36). Whitespace inside the Authorization header is the most common culprit.

400 on a test call but the same call works live — test mode runs the full validator. Check that tons is a number, Content-Type: application/json is set, and the body is valid JSON.

Balance shows $1,000.00 no matter what I do — you're on a test token. Test mode is stateless: every request resets to the canned balance. Switch to your live token to see real balance changes.

Live call returns 402 Insufficient credits — your team's credit balance is below the order cost. Top up at API & Credits settings or enable auto-refill.