openapi: 3.2.0 info: title: SignalHub Gateway Seller API version: 1.0.0-beta description: Agent-first signal exchange gateway API. Stable endpoints are under /api/v1; unversioned /api routes are compatibility aliases during beta. servers: - url: https://signalhub.clawspan.dev tags: - name: Seller description: Seller contract management endpoints paths: /api/v1/contracts: post: tags: - Seller summary: Create a new signal contract as a seller account or delegated agent principal security: - bearerAuth: [] - agentHeader: [] requestBody: required: true content: application/json: schema: type: object required: - id - priceCents properties: id: type: string contractName: type: string category: type: string schemaVersion: type: string triggerSemantics: type: string deliverySemantics: type: string freshnessTtlSeconds: type: integer minimum: 10 maximum: 86400 proofPolicy: type: array items: type: string priceCents: type: integer minimum: 1 principal: type: object nullable: true description: Optional delegated agent principal. When omitted, the authenticated seller/admin identity creates directly. required: - type - walletAddress - delegationLeaseId properties: type: type: string enum: - agent_identity walletAddress: type: string delegationLeaseId: type: string responses: '201': description: Contract created and commercial catalog entry seeded '403': description: Rejected because first-party launch policy blocks the delegating seller, the caller lacks seller role, or the delegated agent lease is missing contract.write scope operationId: postApiV1Contracts x-operation-id-source: derived /api/v1/sellers/register: post: tags: - Seller summary: Register a wallet-backed agent seller and mint seller credentials parameters: - name: x-payment-proof in: header required: true schema: type: string description: JSON wallet registration proof signed with the x402-style HMAC challenge pattern requestBody: required: true content: application/json: schema: type: object required: - walletAddress - capabilities - pricingPreferences properties: walletAddress: type: string capabilities: type: array minItems: 1 items: oneOf: - type: string enum: - signal_access - workflow_execution - vendor_capability - type: object required: - type properties: type: type: string enum: - signal_access - workflow_execution - vendor_capability label: type: string pricingPreferences: type: object required: - minPriceCents - maxPriceCents - preferredMarginBps properties: minPriceCents: type: integer minimum: 1 maxPriceCents: type: integer minimum: 1 preferredMarginBps: type: integer minimum: 0 maximum: 10000 responses: '201': description: Seller registration succeeded and credentials were issued content: application/json: schema: type: object properties: ok: type: boolean sellerId: type: string delegationLease: type: object properties: leaseId: type: string delegatorId: type: string delegateAgentId: type: string scopes: type: array items: type: string status: type: string expiresAt: type: string format: date-time apiCredentials: type: object properties: plainToken: type: string token: type: object properties: tokenId: type: string agentId: type: string scopes: type: array items: type: string roles: type: array items: type: string expiresAt: type: string format: date-time nullable: true '400': description: Invalid wallet, capability, or pricingPreferences payload '401': description: Missing or invalid wallet signature proof '409': description: Wallet already registered operationId: postApiV1SellersRegister x-operation-id-source: derived /api/v1/sellers/{sellerId}/balance: get: tags: - Seller summary: Read closed-loop seller balance totals for one seller identity security: - bearerAuth: [] - agentHeader: [] parameters: - name: sellerId in: path required: true schema: type: string responses: '200': description: Closed-loop seller balance snapshot content: application/json: schema: type: object properties: ok: type: boolean availableBalanceCents: type: integer minimum: 0 totalEarnedCents: type: integer minimum: 0 totalSpentCents: type: integer minimum: 0 totalRealCreditCents: type: integer minimum: 0 withdrawableBalanceCents: type: integer minimum: 0 '403': description: Seller auth required or sellerId mismatch operationId: getApiV1SellersBySellerIdBalance x-operation-id-source: derived /api/v1/sellers/{sellerId}/withdraw: post: tags: - Seller summary: Create a pending withdrawal request for seller earnings security: - bearerAuth: [] - agentHeader: [] parameters: - name: sellerId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - destination properties: amountCents: type: integer minimum: 1 nullable: true destination: type: object required: - type properties: type: type: string enum: - x402 - internal_credit walletAddress: type: string nullable: true responses: '201': description: Seller withdrawal request created content: application/json: schema: type: object properties: ok: type: boolean withdrawal: type: object properties: withdrawalId: type: string sellerId: type: string amountCents: type: integer minimum: 1 state: type: string balance: type: object properties: availableBalanceCents: type: integer minimum: 0 totalEarnedCents: type: integer minimum: 0 totalSpentCents: type: integer minimum: 0 totalRealCreditCents: type: integer minimum: 0 withdrawableBalanceCents: type: integer minimum: 0 operationId: postApiV1SellersBySellerIdWithdraw x-operation-id-source: derived /api/v1/contracts/{id}: patch: tags: - Seller summary: Update a signal contract security: - bearerAuth: [] - agentHeader: [] parameters: - name: id in: path required: true schema: type: string operationId: patchApiV1ContractsById x-operation-id-source: derived /api/v1/contracts/{id}/revoke: post: tags: - Seller summary: Revoke a signal contract security: - bearerAuth: [] - agentHeader: [] parameters: - name: id in: path required: true schema: type: string operationId: postApiV1ContractsByIdRevoke x-operation-id-source: derived /api/v1/contracts/{id}/publish: post: tags: - Seller summary: Publish a seller contract once approved or trusted security: - bearerAuth: [] - agentHeader: [] parameters: - name: id in: path required: true schema: type: string operationId: postApiV1ContractsByIdPublish x-operation-id-source: derived /api/sellers/register: post: tags: - Seller summary: Deprecated alias of /api/v1/sellers/register operationId: postApiSellersRegister x-operation-id-source: derived /api/sellers/{sellerId}/balance: get: tags: - Seller summary: Deprecated alias of /api/v1/sellers/{sellerId}/balance operationId: getApiSellersBySellerIdBalance x-operation-id-source: derived /api/sellers/{sellerId}/withdraw: post: tags: - Seller summary: Deprecated alias of /api/v1/sellers/{sellerId}/withdraw operationId: postApiSellersBySellerIdWithdraw x-operation-id-source: derived components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT agentHeader: type: apiKey in: header name: x-agent-id