openapi: 3.1.0
info:
  title: Grapes Finance API
  description: >-
    Grapes is an embedded stablecoin onramp and offramp solution that enables
    businesses and developers to integrate fiat-to-stablecoin and
    stablecoin-to-fiat transactions. Supports buying and selling stablecoins
    such as USDC and QCAD with CAD and USD across Ethereum, Algorand, and
    Stellar networks.
  version: 1.0.0
  contact:
    name: Grapes Finance Support
    url: https://docs.grapesfinance.com/api-user-guide/
externalDocs:
  description: Grapes Finance API User Guide
  url: https://docs.grapesfinance.com/api-user-guide/

servers:
  - url: https://api.demo.grapesfinance.com
    description: Grapes Demo / Sandbox API

security:
  - ApiKeyAuth: []

tags:
  - name: Users
    description: Account management for users controlling Grapes wallets
  - name: KYC
    description: Identity verification for individuals and businesses
  - name: Wallets
    description: Custodial and non-custodial cryptocurrency wallet operations
  - name: Orders
    description: Fiat-to-stablecoin, stablecoin-to-fiat, and payout orders
  - name: Contacts
    description: Beneficiary management for third-party payouts
  - name: Organizations
    description: Vineyard Manager API for embedded client management

paths:
  /users:
    get:
      tags: [Users]
      summary: List users
      description: Retrieve a list of users associated with the authenticated account.
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      tags: [Users]
      summary: Create user
      description: Create a new user account with Grapes wallet control.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /users/{userId}:
    get:
      tags: [Users]
      summary: Get user
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /kyc:
    post:
      tags: [KYC]
      summary: Submit KYC application
      description: Submit Know Your Customer or Know Your Business verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycApplication'
      responses:
        '201':
          description: KYC application submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycApplication'

  /wallets:
    get:
      tags: [Wallets]
      summary: List wallets
      responses:
        '200':
          description: A list of wallets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Wallet'
    post:
      tags: [Wallets]
      summary: Create wallet
      description: Create a custodial or non-custodial wallet on Ethereum, Algorand, or Stellar.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Wallet'
      responses:
        '201':
          description: Wallet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'

  /orders:
    get:
      tags: [Orders]
      summary: List orders
      responses:
        '200':
          description: A list of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
    post:
      tags: [Orders]
      summary: Create order
      description: Create a fiat-to-stablecoin onramp, stablecoin-to-fiat offramp, or payout order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /contacts:
    get:
      tags: [Contacts]
      summary: List contacts
      responses:
        '200':
          description: A list of beneficiary contacts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
    post:
      tags: [Contacts]
      summary: Create contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Contact created

  /organizations:
    get:
      tags: [Organizations]
      summary: List organizations
      responses:
        '200':
          description: A list of organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
    post:
      tags: [Organizations]
      summary: Create organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organization'
      responses:
        '201':
          description: Organization created

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    User:
      type: object
      properties:
        id: { type: string }
        email: { type: string, format: email }
        firstName: { type: string }
        lastName: { type: string }
        status:
          type: string
          enum: [pending, active, suspended]
        createdAt: { type: string, format: date-time }
    KycApplication:
      type: object
      properties:
        id: { type: string }
        userId: { type: string }
        type:
          type: string
          enum: [individual, business]
        status:
          type: string
          enum: [pending, approved, rejected]
        documents:
          type: array
          items:
            type: object
            properties:
              type: { type: string }
              url: { type: string }
    Wallet:
      type: object
      properties:
        id: { type: string }
        userId: { type: string }
        custody:
          type: string
          enum: [custodial, non-custodial]
        chain:
          type: string
          enum: [ethereum, algorand, stellar]
        address: { type: string }
        balances:
          type: array
          items:
            type: object
            properties:
              asset:
                type: string
                enum: [USDC, QCAD, CAD, USD]
              amount: { type: string }
    Order:
      type: object
      properties:
        id: { type: string }
        type:
          type: string
          enum: [onramp, offramp, payout, swap]
        sourceAsset:
          type: string
          enum: [USDC, QCAD, CAD, USD]
        destinationAsset:
          type: string
          enum: [USDC, QCAD, CAD, USD]
        amount: { type: string }
        status:
          type: string
          enum: [pending, processing, settled, failed]
        createdAt: { type: string, format: date-time }
    Contact:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        email: { type: string, format: email }
        walletAddress: { type: string }
        bankAccount:
          type: object
          properties:
            institution: { type: string }
            accountNumber: { type: string }
            transit: { type: string }
    Organization:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        members:
          type: array
          items:
            type: string
        createdAt: { type: string, format: date-time }