openapi: 3.2.0
info:
  title: Hilt Checkout API
  description: Hilt Pay Workspace and Hilt Pay API routes for zero-custody Solana checkout, MPP metered payment channels, receipts, memberships, entitlements, native subscriptions, webhooks, and support context.
  version: 1.0.0
  contact:
    name: Hilt
    url: https://www.hilt.so
    email: hello@hilt.so
  x-guidance: Start with POST /v1/access/agent-bootstrap. An agent can purchase 30 days of Starter, Growth, or Scale through the matching x402 V2 activation endpoint paid in Solana USDC. For metered integrations, settle PAYMENT-SIGNATURE through POST /v1/access/x402/settle and atomically consume through POST /v1/access/entitlements/consume before serving. Never send private keys, seed phrases, or wallet secrets.
servers:
- url: https://api.hilt.so
tags:
- name: Checkout
paths:
  /v1/pay/broadcast:
    post:
      tags:
      - Checkout
      summary: Record Payment Broadcast
      operationId: record_payment_broadcast_v1_pay_broadcast_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BroadcastRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/automatic-renew/setup:
    post:
      tags:
      - Checkout
      summary: Automatic Renew Setup
      operationId: automatic_renew_setup_v1_pay_automatic_renew_setup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomaticRenewSetupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomaticRenewSetupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/identity/start:
    post:
      tags:
      - Checkout
      summary: Start Checkout Identity Handshake
      operationId: start_checkout_identity_handshake_v1_pay_identity_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityHandshakeStartRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityHandshakeStartResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/identity/complete:
    post:
      tags:
      - Checkout
      summary: Complete Checkout Identity Handshake
      operationId: complete_checkout_identity_handshake_v1_pay_identity_complete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityHandshakeCompleteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityHandshakeCompleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/connect/callback:
    post:
      tags:
      - Checkout
      summary: Phantom Connect Callback
      operationId: phantom_connect_callback_v1_pay_phantom_connect_callback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomConnectCallbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomConnectCallbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/message-url:
    post:
      tags:
      - Checkout
      summary: Phantom Message Url
      operationId: phantom_message_url_v1_pay_phantom_message_url_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomMessageUrlRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomDeeplinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/renewal-message-url:
    post:
      tags:
      - Checkout
      summary: Phantom Renewal Message Url
      operationId: phantom_renewal_message_url_v1_pay_phantom_renewal_message_url_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomRenewalMessageUrlRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomDeeplinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/message/callback:
    post:
      tags:
      - Checkout
      summary: Phantom Message Callback
      operationId: phantom_message_callback_v1_pay_phantom_message_callback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomMessageCallbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomMessageCallbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/renewal-message/callback:
    post:
      tags:
      - Checkout
      summary: Phantom Renewal Message Callback
      operationId: phantom_renewal_message_callback_v1_pay_phantom_renewal_message_callback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomRenewalMessageCallbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomRenewalMessageCallbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/transaction-url:
    post:
      tags:
      - Checkout
      summary: Phantom Transaction Url
      operationId: phantom_transaction_url_v1_pay_phantom_transaction_url_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomTransactionUrlRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomDeeplinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/phantom/transaction/callback:
    post:
      tags:
      - Checkout
      summary: Phantom Transaction Callback
      operationId: phantom_transaction_callback_v1_pay_phantom_transaction_callback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhantomTransactionCallbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhantomTransactionCallbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pay/confirm:
    post:
      tags:
      - Checkout
      summary: Confirm Payment
      operationId: confirm_payment_v1_pay_confirm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AutomaticRenewSetupRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
      type: object
      required:
      - payment_id
      title: AutomaticRenewSetupRequest
    IdentityHandshakeStartResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        status:
          type: string
          title: Status
        wallet_address:
          type: string
          title: Wallet Address
        wallet_source:
          type: string
          title: Wallet Source
        identity_type:
          type: string
          title: Identity Type
        identity_value:
          type: string
          title: Identity Value
        identity_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Identity Display
        challenge_message:
          type: string
          title: Challenge Message
        expires_at:
          type: string
          title: Expires At
      type: object
      required:
      - session_id
      - status
      - wallet_address
      - wallet_source
      - identity_type
      - identity_value
      - challenge_message
      - expires_at
      title: IdentityHandshakeStartResponse
    PhantomRenewalMessageCallbackResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
        automatic_renew_setup_key:
          type: string
          title: Automatic Renew Setup Key
        wallet_address:
          type: string
          title: Wallet Address
        signed_message_b64:
          type: string
          title: Signed Message B64
      type: object
      required:
      - payment_id
      - automatic_renew_setup_key
      - wallet_address
      - signed_message_b64
      title: PhantomRenewalMessageCallbackResponse
    IdentityHandshakeCompleteResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        status:
          type: string
          title: Status
        wallet_address:
          type: string
          title: Wallet Address
        wallet_source:
          type: string
          title: Wallet Source
        identity_type:
          type: string
          title: Identity Type
        identity_value:
          type: string
          title: Identity Value
        identity_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Identity Display
        verified_at:
          type: string
          title: Verified At
        expires_at:
          type: string
          title: Expires At
      type: object
      required:
      - session_id
      - status
      - wallet_address
      - wallet_source
      - identity_type
      - identity_value
      - verified_at
      - expires_at
      title: IdentityHandshakeCompleteResponse
    AutomaticRenewSetupResponse:
      properties:
        setup_key:
          type: string
          title: Setup Key
        instructions:
          items:
            type: object
          type: array
          title: Instructions
        mandate_message:
          type: string
          title: Mandate Message
        renewal_terms:
          type: object
          title: Renewal Terms
        native_subscription:
          anyOf:
          - type: object
          - type: 'null'
          title: Native Subscription
      type: object
      required:
      - setup_key
      - instructions
      - mandate_message
      - renewal_terms
      title: AutomaticRenewSetupResponse
    BroadcastResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
        status:
          type: string
          title: Status
        tx_signature:
          type: string
          title: Tx Signature
      type: object
      required:
      - payment_id
      - status
      - tx_signature
      title: BroadcastResponse
    PhantomMessageCallbackRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        identity_session_id:
          type: string
          title: Identity Session Id
        nonce:
          type: string
          title: Nonce
        data:
          type: string
          title: Data
      type: object
      required:
      - payment_id
      - identity_session_id
      - nonce
      - data
      title: PhantomMessageCallbackRequest
    PhantomTransactionUrlRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        serialized_transaction_b58:
          type: string
          title: Serialized Transaction B58
        handoff_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Handoff Token
      type: object
      required:
      - payment_id
      - serialized_transaction_b58
      title: PhantomTransactionUrlRequest
    PhantomTransactionCallbackResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
        wallet_address:
          type: string
          title: Wallet Address
        serialized_transaction_b64:
          type: string
          title: Serialized Transaction B64
      type: object
      required:
      - payment_id
      - wallet_address
      - serialized_transaction_b64
      title: PhantomTransactionCallbackResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PhantomDeeplinkResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
        deeplink_url:
          type: string
          title: Deeplink Url
      type: object
      required:
      - payment_id
      - deeplink_url
      title: PhantomDeeplinkResponse
    PhantomConnectCallbackResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
        wallet_address:
          type: string
          title: Wallet Address
        wallet_source:
          type: string
          title: Wallet Source
        session_stored:
          type: boolean
          title: Session Stored
      type: object
      required:
      - payment_id
      - wallet_address
      - wallet_source
      - session_stored
      title: PhantomConnectCallbackResponse
    PhantomRenewalMessageUrlRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        automatic_renew_setup_key:
          type: string
          title: Automatic Renew Setup Key
        handoff_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Handoff Token
      type: object
      required:
      - payment_id
      - automatic_renew_setup_key
      title: PhantomRenewalMessageUrlRequest
    ConfirmResponse:
      properties:
        status:
          type: string
          title: Status
        payment_id:
          type: string
          title: Payment Id
        delivery_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Type
        delivery_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Value
        amount_minor_units:
          type: integer
          title: Amount Minor Units
        delivery_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Status
        membership_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Membership Id
        membership_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Membership Status
        membership_period_end_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Membership Period End At
        automatic_renew_setup_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Setup Status
        automatic_renew_setup_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Setup Error
      type: object
      required:
      - status
      - payment_id
      - amount_minor_units
      title: ConfirmResponse
    PhantomRenewalMessageCallbackRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        automatic_renew_setup_key:
          type: string
          title: Automatic Renew Setup Key
        nonce:
          type: string
          title: Nonce
        data:
          type: string
          title: Data
      type: object
      required:
      - payment_id
      - automatic_renew_setup_key
      - nonce
      - data
      title: PhantomRenewalMessageCallbackRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    IdentityHandshakeCompleteRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        wallet_address:
          type: string
          title: Wallet Address
        signed_message_b64:
          type: string
          title: Signed Message B64
      type: object
      required:
      - session_id
      - wallet_address
      - signed_message_b64
      title: IdentityHandshakeCompleteRequest
    BroadcastRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        tx_signature:
          type: string
          title: Tx Signature
        payer_wallet:
          anyOf:
          - type: string
          - type: 'null'
          title: Payer Wallet
        wallet_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Wallet Source
      type: object
      required:
      - payment_id
      - tx_signature
      title: BroadcastRequest
    PhantomConnectCallbackRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        phantom_encryption_public_key:
          type: string
          title: Phantom Encryption Public Key
        nonce:
          type: string
          title: Nonce
        data:
          type: string
          title: Data
      type: object
      required:
      - payment_id
      - phantom_encryption_public_key
      - nonce
      - data
      title: PhantomConnectCallbackRequest
    PhantomMessageCallbackResponse:
      properties:
        payment_id:
          type: string
          title: Payment Id
        identity_session_id:
          type: string
          title: Identity Session Id
        wallet_address:
          type: string
          title: Wallet Address
        verified_at:
          type: string
          title: Verified At
      type: object
      required:
      - payment_id
      - identity_session_id
      - wallet_address
      - verified_at
      title: PhantomMessageCallbackResponse
    IdentityHandshakeStartRequest:
      properties:
        slug:
          type: string
          title: Slug
        wallet_address:
          type: string
          title: Wallet Address
        wallet_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Wallet Source
        customer_reference_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Reference Type
        customer_reference_value:
          type: string
          title: Customer Reference Value
        customer_reference_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Reference Display
      type: object
      required:
      - slug
      - wallet_address
      - customer_reference_value
      title: IdentityHandshakeStartRequest
    PhantomMessageUrlRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        identity_session_id:
          type: string
          title: Identity Session Id
        handoff_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Handoff Token
      type: object
      required:
      - payment_id
      - identity_session_id
      title: PhantomMessageUrlRequest
    PhantomTransactionCallbackRequest:
      properties:
        payment_id:
          type: string
          title: Payment Id
        nonce:
          type: string
          title: Nonce
        data:
          type: string
          title: Data
      type: object
      required:
      - payment_id
      - nonce
      - data
      title: PhantomTransactionCallbackRequest
    ConfirmRequest:
      properties:
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        product_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Id
        tx_signature:
          type: string
          title: Tx Signature
        payer_wallet:
          type: string
          title: Payer Wallet
        wallet_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Wallet Source
        identity_session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Identity Session Id
        customer_reference_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Reference Type
        customer_reference_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Reference Value
        customer_reference_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Reference Display
        payment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Id
        automatic_renew_setup_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Setup Key
        automatic_renew_message_signature_b64:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Message Signature B64
        automatic_renew_native_setup_signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Native Setup Signature
        automatic_renew_native_subscription_authority_pda:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Native Subscription Authority Pda
        automatic_renew_native_subscription_pda:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Native Subscription Pda
        automatic_renew_native_plan_pda:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Native Plan Pda
        automatic_renew_native_payer_token_account:
          anyOf:
          - type: string
          - type: 'null'
          title: Automatic Renew Native Payer Token Account
      type: object
      required:
      - tx_signature
      - payer_wallet
      title: ConfirmRequest
x-hilt-agent-commerce:
  offer: https://api.hilt.so/v1/agent-commerce/offer
  catalog: https://api.hilt.so/agent-catalog.json
  pricing: https://api.hilt.so/pricing
  x402: https://api.hilt.so/x402