Grapes Finance Organizations API (Vineyard Manager)

The Organizations API enables businesses to embed Grapes functionality without requiring direct client authentication, allowing management of client wallets and submission of transactions on their behalf.

OpenAPI Specification

grapes-finance-openapi.yml Raw ↑
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 }