Fin

Fin Virtual Accounts API

Create and manage virtual accounts for USD to USDC conversions

Documentation GitHub OpenAPI

Operations 6

POST /v2/customers/{customer_id}/virtual-accounts Create Virtual Account V2 #

GET /v2/customers/{customer_id}/virtual-accounts List Virtual Accounts V2 #

GET /v1/customers/virtual-account List Virtual Accounts V1

POST /v1/customers/virtual-account Create Virtual Account

PUT /v1/customers/virtual-account Update Virtual Account

GET /v1/virtual-account/{virtual_account_id}/transactions Fetch Virtual Account Transactions

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/fin-virtual-accounts-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Fin.com Virtual Accounts API
  version: 1.0.0
  description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
  description: Sandbox server
- url: https://api.fin.com
  description: Production server
tags:
- name: Virtual Accounts
  description: Create and manage virtual accounts for USD to USDC conversions
paths:
  /v2/customers/{customer_id}/virtual-accounts:
    post:
      operationId: createVirtualAccountV2
      summary: Create Virtual Account V2
      description: Create a virtual bank account for a specific customer to convert fiat deposits to crypto. The `customer_id` path parameter identifies the customer for whom the virtual account is being created.
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the customer to create the virtual account for.
        example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - destination
              - source
              - developer_fee
              properties:
                destination:
                  type: object
                  required:
                  - wallet
                  - currency
                  - rail
                  properties:
                    wallet:
                      type: string
                      description: Destination wallet address in hexadecimal format (0x...)
                      example: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                    currency:
                      type: string
                      enum:
                      - USDC
                      example: USDC
                    rail:
                      type: string
                      enum:
                      - POLYGON
                      example: POLYGON
                source:
                  type: object
                  required:
                  - currency
                  - rail
                  properties:
                    currency:
                      type: string
                      enum:
                      - USD
                      - EUR
                      - MXN
                      example: USD
                    rail:
                      type: string
                      enum:
                      - ACH
                      - SWIFT
                      - FEDWIRE
                      - FEDNOW
                      - SEPA
                      - SPEI
                      example: FEDWIRE
                developer_fee:
                  type: object
                  required:
                  - percentage
                  - fixed
                  properties:
                    percentage:
                      type: number
                      example: 0.1
                    fixed:
                      type: number
                      example: 0.1
            example:
              destination:
                wallet: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                currency: USDC
                rail: POLYGON
              source:
                currency: USD
                rail: FEDWIRE
              developer_fee:
                percentage: 0.1
                fixed: 0.1
      responses:
        '200':
          description: Virtual account created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                      status:
                        type: string
                        enum:
                        - PROCESSING
                        - IN_COMPLIANCE
                        - REQUEST_FOR_INFORMATION
                        - ACTIVE
                        - INACTIVE
                        - DECLINED
                        example: PROCESSING
                      customer_id:
                        type: string
                        format: uuid
                        example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                      created_at:
                        type: string
                        format: date-time
                        example: '2026-04-04T11:05:20.963676Z'
                      rfi:
                        type: object
                        nullable: true
                        example: null
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      id: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                      status: PROCESSING
                      customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                      created_at: '2026-04-04T11:05:20.963676Z'
                      rfi: null
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      operationId: listVirtualAccountsV2
      summary: List Virtual Accounts V2
      description: Retrieve a list of all virtual accounts for a specific customer
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier for the customer
        example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: Virtual accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      virtual_accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                            status:
                              type: string
                              enum:
                              - PROCESSING
                              - IN_COMPLIANCE
                              - REQUEST_FOR_INFORMATION
                              - ACTIVE
                              - INACTIVE
                              - DECLINED
                              example: ACTIVE
                            developer_fee_percent:
                              type: number
                              nullable: true
                              example: 0
                            developer_fee_fixed:
                              type: number
                              nullable: true
                              example: 0.3
                            customer_id:
                              type: string
                              format: uuid
                              example: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                            created_at:
                              type: string
                              format: date-time
                              example: '2026-04-04T11:05:20.963676Z'
                            updated_at:
                              type: string
                              format: date-time
                              example: '2026-04-04T11:05:20.963676Z'
                            deposit_instructions:
                              type: object
                              nullable: true
                              description: null when status is PROCESSING
                              properties:
                                currency:
                                  type: string
                                  example: USD
                                bank_name:
                                  type: string
                                  example: Bank of Nowhere
                                bank_address:
                                  type: string
                                  example: 1800 North Pole St., Orlando, FL 32801
                                bank_routing_number:
                                  type: string
                                  example: '101019644'
                                bank_account_number:
                                  type: string
                                  example: '2611508020'
                                payment_rails:
                                  type: array
                                  items:
                                    type: string
                                  example:
                                  - ACH
                                  - FEDWIRE
                                bank_country:
                                  type: string
                                  nullable: true
                                  example: null
                                account_type:
                                  type: string
                                  nullable: true
                                  example: null
                                bank_code:
                                  type: string
                                  nullable: true
                                  example: null
                            destination:
                              type: object
                              properties:
                                currency:
                                  type: string
                                  enum:
                                  - USDC
                                  example: USDC
                                destination_chain:
                                  type: string
                                  enum:
                                  - POLYGON
                                  example: POLYGON
                                address:
                                  type: string
                                  example: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                            rfi:
                              type: object
                              nullable: true
                              example: null
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 2
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      virtual_accounts:
                      - id: 024e784b-bc27-4a4c-82ee-80000fbf53c5
                        status: PROCESSING
                        developer_fee_percent: 0
                        developer_fee_fixed: 0.3
                        customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                        created_at: '2026-04-04T11:05:20.963676Z'
                        updated_at: '2026-04-04T11:05:20.963676Z'
                        deposit_instructions: null
                        destination:
                          currency: USDC
                          destination_chain: POLYGON
                          address: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                        rfi: null
                      - id: 1c1919e3-ce2e-4728-9efe-12b8be8e964d
                        status: ACTIVE
                        developer_fee_percent: 0
                        developer_fee_fixed: null
                        customer_id: 0fb72092-22a8-4df8-a6d9-1a28f86b7d44
                        created_at: '2026-04-04T11:04:16.156771Z'
                        updated_at: '2026-04-04T11:04:16.156771Z'
                        deposit_instructions:
                          currency: USD
                          bank_name: Bank of Nowhere
                          bank_address: 1800 North Pole St., Orlando, FL 32801
                          bank_routing_number: '101019644'
                          bank_account_number: '2611508020'
                          payment_rails:
                          - ACH
                          - FEDWIRE
                          bank_country: null
                          account_type: null
                          bank_code: null
                        destination:
                          currency: USDC
                          destination_chain: POLYGON
                          address: '0x6e41e83d406185b358bd72111ab1206cb82eb67f'
                        rfi: null
                      pagination:
                        current_page: 1
                        per_page: 10
                        total_page: 1
                        total: 2
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/customers/virtual-account:
    get:
      summary: List Virtual Accounts V1
      description: Retrieve a list of all virtual accounts for a specific customer
      x-mint:
        content: "<Warning>\n  This endpoint was deprecated on May 20, 2026. Use [List Virtual Accounts V2](https://developer.fin.com/api-reference/virtual-accounts/list-virtual-accounts-v2) instead.\n</Warning>\n"
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
        example: 196ce546-900d-4294-90ca-5546a5923f35
      responses:
        '200':
          description: Virtual accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - virtual_accounts
                    - pagination
                    properties:
                      virtual_accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/VirtualAccount'
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 6
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      summary: Create Virtual Account
      description: Create a virtual bank account for a customer to convert USD deposits to USDC on Polygon
      x-mint:
        content: "<Warning>\n  This endpoint was deprecated on May 20, 2026. Use [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) instead.\n</Warning>\n"
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_id
              - destination_currency
              - destination_chain
              - source_rail
              - source_currency
              - destination_wallet_address
              - developer_fee_percentage
              properties:
                customer_id:
                  type: string
                  format: uuid
                  example: 5a6f47f7-7326-409f-a4da-90e409133fb8
                destination_currency:
                  type: string
                  enum:
                  - USDC
                  default: USDC
                destination_chain:
                  type: string
                  enum:
                  - POLYGON
                  default: POLYGON
                source_rail:
                  type: string
                  example: ACH
                source_currency:
                  type: string
                  example: USD
                destination_wallet_address:
                  type: string
                  example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29'
                developer_fee_percentage:
                  type: number
                  example: 1.5
      responses:
        '200':
          description: Virtual account created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualAccount'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      summary: Update Virtual Account
      description: Update an existing virtual bank account's developer fee percentage and destination wallet address
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - customer_id
              properties:
                id:
                  type: string
                  format: uuid
                  example: f8715e46-f46a-41dc-94ec-bd9797683510
                customer_id:
                  type: string
                  format: uuid
                  example: 22c6b566-5ecc-49b7-b812-076c64735596
                developer_fee_percentage:
                  type: number
                  example: 1.25
                destination_wallet_address:
                  type: string
                  example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29'
      responses:
        '200':
          description: Virtual account updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualAccount'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/virtual-account/{virtual_account_id}/transactions:
    get:
      summary: Fetch Virtual Account Transactions
      description: Retrieve a paginated list of all transactions for a specific virtual account
      tags:
      - Virtual Accounts
      security:
      - bearerAuth: []
      parameters:
      - name: virtual_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: 3e7ce5ef-09bc-4e80-97f1-651ac483546f
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Virtual account transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    properties:
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: e34a382f-f0b6-40f2-b53b-97cb31f0506c
                            transaction_type:
                              type: string
                              example: ONRAMP
                            beneficiary_id:
                              type: string
                              format: uuid
                              nullable: true
                            hash:
                              type: string
                              nullable: true
                            transaction_ref_id:
                              type: string
                              format: uuid
                            from_amount:
                              type: number
                              example: 0
                            payout_amount:
                              type: number
                              example: 0
                            processing_amount:
                              type: number
                              nullable: true
                            status:
                              type: string
                              example: COMPLETED
                            fx_rate:
                              type: number
                              example: 0
                            developer_fee:
                              type: number
                              example: 0
                            developer_fee_percentage:
                              type: number
                              example: 0
                            developer_fee_fixed:
                              type: number
                              nullable: true
                            from_currency:
                              type: string
                              example: USD
                            payout_currency:
                              type: string
                              example: USDC
                            virtual_account_id:
                              type: string
                              format: uuid
                            created_at:
                              type: string
                              format: date-time
                            updated_at:
                              type: string
                              format: date-time
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 4
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  responses:
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Resource not found
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
    ValidationError:
      description: Failed due to a formatting error.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            properties:
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: string
  parameters:
    PerPageParam:
      name: per_page
      in: query
      description: Number of items to return per page
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 512
    CurrentPageParam:
      name: current_page
      in: query
      description: The page number to retrieve
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
  schemas:
    VirtualAccount:
      type: object
      required:
      - id
      - status
      - developer_fee_percent
      - customer_id
      - created_at
      - updated_at
      - deposit_instructions
      - destination
      properties:
        id:
          type: string
          format: uuid
          example: 92eceee4-ec6a-4fe3-a224-f5914cabe001
        status:
          type: string
          example: ACTIVE
        developer_fee_percent:
          type: number
          example: 1.65
        customer_id:
          type: string
          format: uuid
          example: 196ce546-900d-4294-90ca-5546a5923f35
        created_at:
          type: string
          format: date-time
          example: '2025-12-22T06:09:23.456895Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-12-22T06:09:23.456895Z'
        deposit_instructions:
          type: object
          properties:
            currency:
              type: string
              example: USD
            bank_name:
              type: string
              example: Bank of Nowhere
            bank_address:
              type: string
              example: 1800 North Pole St., Orlando, FL 32801
            bank_routing_number:
              type: string
              example: '101019644'
            bank_account_number:
              type: string
              example: '900336047672'
            bank_beneficiary_name:
              type: string
              example: Portgas D Ace
            bank_beneficiary_address:
              type: string
              example: 321 British Columbia City, British Columbia, BC V0C 1Y0, CA
            payment_rails:
              type: array
              items:
                type: string
              example:
              - ACH
              - FEDWIRE
        destination:
          type: object
          properties:
            currency:
              type: string
              enum:
              - USDC
              default: USDC
            destination_chain:
              type: string
              enum:
              - POLYGON
              - ETHEREUM
            address:
              type: string
              example: '0x7f1568190e318da16a9ef5a46cba19d5b97d9b29'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication. Obtain token from [Issue a Token](https://developer.fin.com/api-reference/authentication/issue-a-token) endpoint