Platform Architecture & Money Movement

Knit combines a traditional business wallet with a dedicated API account so you can collect, store, and disburse crypto without exposing your main treasury. This page explains the moving parts so you can reason about balances, authentication, and webhook side-effects before touching any endpoint.

Wallet Layers

Because API services do not have their own spendable balances, every call that credits or debits value ultimately updates the API Account.

Money-Movement Flows (What Merchants Should Know)

All activity you trigger through the API ultimately affects the API Account balance. Keep these scenarios in mind when planning your integration:

1. Fund the API Account from the dashboard. Move USDT/USDC from the business wallet into the API account before creating payouts. This is a manual step so you stay in control of how much balance programmatic flows can touch.
2. Collections credit the API Account. Every one-time collection address you create funnels the confirmed proceeds into the API account automatically—no extra transfer needed.
3. API Wallet deposits also credit the API Account. Reusable wallets (for customer balances or recurring payments) record each deposit and then top up the API account so the funds are ready for payouts or internal transfers.
4. Payouts debit the API Account. When you call POST /api/v1/payouts, Knit verifies that the API account for the specified token has enough balance, locks it, and then submits the transfer. Successful completions trigger the PAYOUT_SUCCESSFUL webhook.
5. Return unused balance when you’re done. If you want to move funds back to the main business wallet, use the dashboard action to transfer from API account → business wallet.

Whenever you see balanceBefore / balanceAfter in API responses, those values represent the API account ledger. Monitoring that balance is the best way to determine how much runway you have left for programmatic payouts.

Authentication Path

Every /api/v1/** route expects OAuth 2.0 client-credential tokens. Provide Authorization: Bearer <access-token> and the platform will:

1. Validate the token signature/expiry and extract the OAuth client plus its scopes.
2. Resolve the business tied to that client, make sure the caller’s IP address is on the approved list, and continue the request on behalf of that business.
3. Confirm the route’s required scope (for example payouts:write for POST /api/v1/payouts). Requests without the correct scope are rejected with “Insufficient permissions”.

The X-API-KEY header still works for legacy integrations, but we recommend migrating to OAuth for scoped access control, richer audit logs, and easier credential rotation.

Webhooks & Observability

• Webhook delivery: Knit signs every webhook with your business secret and retries failed deliveries for up to 12 hours (three attempts). Keep your endpoint idempotent so duplicate deliveries are safe.
• Event coverage: Collections emit CREATED/SUCCESSFUL/FAILED events; payouts emit SUCCESSFUL once they are fully settled on-chain.
• Usage metrics: You can monitor request counts, success/error rates, and latency via the Analytics section of the dashboard (API Glance).

Error & Response Envelope

All controllers return the shared ApiResponse format:

{
  "success": true,
  "statusCode": 200,
  "message": "...",
  "data": {},
  "pagination": { /* optional */ }
}

Errors reuse the same structure with success: false and a descriptive message. Validation errors include an errors object when thrown from a BaseRequest.

Keep this context in mind as you explore the per-endpoint documentation in the sidebar.