Hosted Flows

Some actions should stay direct onchain calls. Others should be hosted product flows.

This means the platform should support two modes over time:

• hosted for normal users and interactive product flows
• self-custody for agents, bots, and advanced users who want their own signer

Examples of hosted flows:

• market validation
• draft generation
• submit-and-wait creation
• future relayed actions
• future CLOB order placement and cancellation

Auth model

For normal user-facing hosted platform calls, the default model is:

1. project API key identifying the integrating app
2. authenticated end-user session identifying the current user
3. managed wallet / smart wallet execution behind the scenes

This is the model we want across the SDK and React hooks because it matches the intended UX:

• Privy embedded wallets
• silent hosted creation flows
• session-backed managed execution
• product teams that should not have to wire wallet signatures into every user action

Hybrid model

The hosted lane should be the default, but it should not be the only lane.

For agents and bots, we also want a self-custody mode:

1. project API key identifying the integrating app
2. local signer imported or generated by the CLI / script
3. direct onchain writes or lower-level SDK flows where appropriate

That gives us:

• a clean user-facing login flow for normal apps
• a non-interactive mode for automation
• parity with Context-style agent workflows without forcing all users into local key management

The important constraint is that these should stay explicit modes, not one blurry auth system.

Why this is the default

The project key tells us which app is integrating.

The end-user session tells us who is using that app.

The platform then maps that user to the correct managed wallet infrastructure and executes the hosted action without a visible signing step.

That is the right default for:

• draft validation
• draft generation
• market creation
• future hosted redeem/refund/finalize flows when policy allows

SDK behavior

Hosted methods in the SDK should internally:

1. send the project API key and environment
2. rely on the app's authenticated user session
3. call the hosted endpoint
4. poll async jobs when execution is not immediate

That keeps the calling code simple while preserving app and user identity.

Example shape

const draft = await client.drafts.generate({
  prompt: "Will we ship v2 before July 1?",
  type: "parimutuel",
});

const market = await client.markets.createAndWait({
  draftId: draft.id,
});

Under the hood, the request context is closer to:

{
  "headers": {
    "x-platform-api-key": "platform_pk_test_..."
  },
  "session": "user session from the host app",
  "payload": {
    "draftId": "draft_123"
  }
}

React behavior

React hooks should hide most of this wiring:

• read the project API key from MarketsProvider
• integrate with the app's auth/session layer
• track wallet provisioning and readiness state
• submit the hosted action

So components can stay focused on product behavior instead of auth plumbing.

Advanced signed-hosted flows later

We should still leave room for a second hosted pattern for advanced or self-custody cases such as:

• CLOB orders and cancels
• self-custody or external-signer integrations
• typed-data-heavy relayer actions

Those flows may require:

• explicit wallet address in the payload
• wallet signature or typed-data signature
• app auth separate from wallet auth

That path should be additive. It should not replace the default hosted model for parimutuel creation.