For a decision maker evaluating Connect, and for the operator's engineer who will build it.

FAQ

Do I have to use the MCP, or can I use REST only?

You can use REST only. Every action an agent takes through a connect_* tool has a REST route under https://api.onehazel.com/onehazel-api/operators/me/connect/, called with your signed-in session token, and the read-only material (the contract, the samples, the conformance scenarios) is published on these pages. The MCP is a faster way in, never the only one.

Can I integrate without an AI agent at all?

Yes. Getting started is a six-step track for a person, with a check you can run at the end of each step. The generated samples give you a working module to start from.

Can the agent go live by itself?

No. The most an agent can do is create a vendor connection in the inactive state (connect_activate) and notify your team that it is ready for review (connect_request_go_live). A person on your team clicks Go live on the connection page; no tool or API can do that step.

What data leaves my platform?

Only what the modules you build return or send. The player module returns currency, country, account status and active restrictions, and no further personal data is requested. The wallet module returns balances and transaction results, and events.push carries whatever player and activity data you choose to push. Conformance runs use only the test players you name.

Where are the secrets stored?

The signing secret and the callback key are generated by OneHazel at registration (unless you supply your own callback key as callbackKey), stored encrypted at rest, and shown to you once in plain text. The machines that run conformance do not hold the encryption key; they fetch one run's secrets for the length of that run. Tool output and stored conformance evidence mask keys and secrets.

Can I rotate the secrets?

You can rotate at any time with connect_rotate_secret or POST /operators/me/connect/endpoints/<module>/rotate. Pass what: signing_secret, callback_key or both. The default is both. Each new value is returned once, with a save_as block that names the adapter and sample variables to write it to. The previous signing secret and callback key stay accepted for one hour, so you can deploy the new values without downtime. A rotated callback key is minted by OneHazel. To use your own key instead, register again with callbackKey. Registering again also rotates the signing secret, and a callbackKey that differs from the stored one keeps the old key valid for the same hour.

Can I run conformance myself?

Yes, as often as you need within a limit of 10 runs per hour: start a run with connect_run_conformance or POST /operators/me/connect/conformance, and read the per-scenario requests and responses with connect_conformance_evidence. Between runs you can replay the scenarios against your local build using signForTest from @onehazel/connect and the scenario list on Conformance.

What happens with test versus live traffic?

Every call OneHazel makes to your wallet and player modules carries X-OneHazel-Env: test or live. Conformance always sends test, and your module must route test to a test player or sandbox ledger and never to a real-money wallet. Real player traffic after go-live is live.

Which languages have samples?

TypeScript with Express or Fastify, Python with FastAPI, and PHP with no framework or with Laravel, for the wallet, player and webhook.receive modules. For any other stack, generate a server stub from the OpenAPI document and add the wire rules from the contract. See Samples.

Is the contract versioned, and how will v2 be announced?

Yes. The contract is Operator Contract v1 under /connect/v1; additive changes raise its minor version, and a breaking change would ship as /connect/v2 with v1 kept for 12 months. Breaking changes are announced as described in the deprecation policy.

What does evidence: derived mean?

In connect_status, evidence: derived means no conformance run backs this module; in v1 that is launch, widget, attribution and events.push. Their state follows a rule instead: launch follows wallet, widget is constant, attribution follows a recorded click and events.push follows your first pushed data. evidence: run means a finished conformance run backs the state.

Why are there two signature formats?

Wallet and player calls use a timestamped signature plus a bearer key, because they move money and need replay protection. Webhook deliveries keep the format of OneHazel's existing webhook engine (sha256= over the raw body), so receivers already in service keep working; deduplicating on deliveryId is their replay defence.

Do I have to build every module?

No. Each Marketplace connector lists the modules it requires, and you build only the modules your chosen vendors need. connect_status and the Integrate with AI tab show which connections are ready once their required modules are conformant.

What does OneHazel need from me to run conformance?

A public https base URL for each module you host, a funded test player for wallet, and for player a test player plus a second test player with an active restriction. Nothing in a conformance run touches a real player.