Core and App Integration#

Core and App integrations should generate types from the same production OpenAPI revision. Do not maintain handwritten event unions or public transport route mappings.

Generate the contract#

bashcurl -fsS https://api.artery.questflow.ai/docs-json -o artery-openapi.json

The create and edit APIs use subscriptions[]. The sample-payload response is a discriminated union over CloudEvents type, with event-specific exact data schemas.

For account events, consume the generated market snapshot directly. App and Core must not perform a second Gamma lookup or join by title. Prefer market.title plus market.outcome.label; use a shortened market.providerMarketId or market.symbol only when display metadata is null. Persist the whole snapshot with the consumed event so historical UI does not change after catalog refreshes.

The Activity response uses type as its wire discriminator and activityType as its user-facing category. In particular, type=trade with activityType=liquidation must render as Liquidated/ADL, while type=settlement must render its action and result instead of Bought/Sold.

Receiver order of operations#

1. Read the raw request bytes and verify X-Artery-Signature using the timestamped algorithm in Payload Shapes.
2. Parse JSON only after signature verification succeeds.
3. Select the generated event type using CloudEvent type.
4. Reject unsupported major versions into a visible dead-letter path.
5. Atomically persist the event id before returning 2xx.
6. Apply revisions in qfrevision order within qfcorrelationid.
7. Preserve financial decimals as strings or arbitrary-precision values.

tsswitch (event.type) {
  case 'com.questflow.broker.trade.executed.v1':
    await acceptBrokerTrade(event);
    break;
  case 'com.questflow.broker.funding.updated.v1':
    await acceptBrokerFunding(event);
    break;
  case 'com.questflow.broker.position.liquidated.v1':
    await acceptBrokerLiquidation(event);
    break;
  default:
    await deadLetterUnsupportedVersion(event);
}

Release checklist#

• Pin the OpenAPI artifact or its checksum in both Core and App.
• Validate every consumed fixture against the generated schema.
• Test valid, invalid, stale, and tampered signatures.
• Deliver the same id repeatedly and confirm idempotency.
• Test two revisions under one correlation ID.
• Verify unknown versions are observable and replayable.
• Run create → list → edit → test → delivery history → delete before enabling production traffic.
• Verify Order, Trade, Redeem/Settlement, and Liquidation fixtures render market.title and market.outcome.label, with an abbreviated ID fallback.
• Verify activityType keeps normal losing trades, settlement Loss, and liquidation/ADL visually distinct and non-duplicated.