> ## Documentation Index > Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Whitelist a company wallet > Register a company crypto wallet for use in ramp requests. Registers a new company wallet in `PENDING` status. To verify ownership, send 1 USDC from the wallet to the deposit address returned by [Get deposit wallets](/api-reference/Fundflow-API/deposit-wallets/list-deposit-wallets). **Concept guide:** [Account management](/guides/payments/accounts) New wallets start as `PENDING` and must be verified before use. Never share private keys or seed phrases — only the wallet address is required. ## OpenAPI ````yaml api-reference/Fundflow-API.yaml POST /v1/company-wallets openapi: 3.1.0 info: title: Fundflow API description: > Fundflow API provides endpoints for managing cryptocurrency on-ramp and off-ramp requests, company bank accounts, wallets, and user management for blockchain payment operations. ## Overview The Fundflow API enables companies to: - Create and manage on-ramp (fiat to crypto) and off-ramp (crypto to fiat) requests - Manage company bank accounts across multiple payment networks (SEPA, ACH, SWIFT, etc.) - Manage company cryptocurrency wallets across multiple blockchains - Handle user roles and permissions within the company - Calculate fees and retrieve exchange rate information ## Authentication All endpoints require OAuth2 authentication using a bearer token that is retrieved from authentication endpoint using your client_id and client_secret. ## Optimistic Locking Many write operations use optimistic locking via a `version` field to prevent concurrent updates. When a version conflict occurs (HTTP 409), you must: 1. Fetch the latest version of the resource 2. Reapply their changes to the updated resource 3. Retry the operation with the new version number ## Status Workflows ### Ramp Request Status Flow - **AWAITING_APPROVAL** → **AWAITING_FUNDS** (after approval) - **AWAITING_APPROVAL** → **CANCELLED** (cancelled by requester) - **AWAITING_APPROVAL** → **REJECTED** (rejected by company admin) - **AWAITING_APPROVAL** → **DENIED** (denied by Venly admin) - **AWAITING_APPROVAL** → **BLOCKED** (blocked by Venly admin) - **AWAITING_FUNDS** → **PROCESSING** (payment received/initiated) - **PROCESSING** → **SUCCEEDED** (transaction completed) - **PROCESSING** → **FAILED** (transaction failed) contact: name: Venly url: https://venly.io email: contact@venly.io version: 1.7.0 servers: - url: https://api-fundflow.venly.io description: Production - url: https://api-fundflow-staging.venly.io description: Staging security: [] tags: - name: Ramp Requests description: >- On-ramp (fiat to crypto) and off-ramp (crypto to fiat) request lifecycle and management - name: Fees description: Fee configuration and per-request fee calculation - name: Company Wallets description: Company cryptocurrency wallet whitelisting, verification, and management - name: Company Bank Accounts description: >- Company bank account whitelisting and management across payment networks (SEPA, ACH, SWIFT, and more) - name: Deposit Wallets description: >- Venly deposit wallet addresses for wallet-ownership verification and off-ramp settlement - name: Crypto Currencies description: >- Cryptocurrencies supported for ramp operations, organised by blockchain network - name: Fiat Currencies description: Fiat currencies supported for ramp operations - name: Blockchain Networks description: Blockchain networks supported for cryptocurrency operations - name: Bank Account Configuration description: Enabled bank account types, supported countries, and supported currencies - name: Company description: Authenticated company details and KYB status - name: Users description: Company user management, roles, and permissions - name: Authentication description: Authenticated user profile, company affiliation, and assigned authorities paths: /v1/company-wallets: post: tags: - Company Wallets summary: Whitelist a company wallet description: > Registers a new company cryptocurrency wallet with PENDING verification status and requires verification before it can be used in ramp requests. After creating the wallet, you must verify ownership by sending 1 USDC from the wallet to the deposit address that can be retrieved from the Get Deposit Wallets endpoint. operationId: create_1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCompanyWalletRequest' responses: '201': description: Company wallet successfully created content: '*/*': schema: type: object properties: success: type: boolean default: true result: $ref: '#/components/schemas/CompanyWalletDto' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '415': $ref: '#/components/responses/UnsupportedMediaType' '500': $ref: '#/components/responses/InternalServerError' security: - OAuth2: - manage:company-wallet components: schemas: CreateCompanyWalletRequest: type: object title: Create Company Wallet description: Request to register a new cryptocurrency wallet for the company required: - address - chain properties: description: type: string maxLength: 500 minLength: 0 description: Optional description for the wallet example: Main treasury wallet address: type: string maxLength: 255 minLength: 0 description: The blockchain wallet address example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' chain: type: string description: The blockchain network for this wallet enum: - ETHEREUM - POLYGON - BASE - ARBITRUM - SUI CompanyWalletDto: type: object description: Company cryptocurrency wallet details properties: id: type: string format: uuid companyId: type: string format: uuid description: type: string description: User-provided description address: type: string description: Blockchain wallet address chain: type: string description: Blockchain network enum: - ETHEREUM - POLYGON - BASE - ARBITRUM - SUI verificationStatus: type: string description: | Verification status of the wallet. enum: - PENDING - VERIFIED - DENIED verifiedAt: type: string format: date-time description: When wallet was verified (if applicable) createdAt: type: string format: date-time updatedAt: type: string format: date-time version: type: integer format: int64 ErrorResponse: type: object description: Error response wrapper properties: success: type: boolean default: false errors: type: array items: $ref: '#/components/schemas/ErrorBody' result: type: object nullable: true ErrorBody: type: object description: Individual error details properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message responses: BadRequest: description: When the request contains invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: validation-error message: A descriptive error message Unauthorized: description: When the user is not authorized to access the resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: UNAUTHORIZED message: Access is denied. Forbidden: description: When a user doesn't have proper security authority content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: FORBIDDEN message: User doesn't have proper authority to access this resource NotFound: description: When a resource is not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: NOT_FOUND MethodNotAllowed: description: When the HttpMethod is not supported content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: METHOD_NOT_SUPPORTED message: HttpMethod is not supported. Supported methods are [..] UnsupportedMediaType: description: Usually when the input is not a valid json content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: INVALID_MEDIA_TYPE InternalServerError: description: When there's an unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: INTERNAL_SERVER_ERROR message: A description of the error (optional) securitySchemes: OAuth2: type: oauth2 description: OAuth2 authentication via Venly Identity Platform flows: implicit: authorizationUrl: >- https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/auth scopes: openid: OpenID Connect scope view:ramp-request: View ramp requests create:ramp-request: Create ramp requests edit:ramp-request: Edit ramp request amounts approve:ramp-request: Approve ramp requests reject:ramp-request: Reject ramp requests cancel:ramp-request: Cancel ramp requests sign-off:ramp-request: Sign off on ramp requests (add transaction hash) export:ramp-requests: Export ramp requests view:company-wallet: View company wallets manage:company-wallet: Create and manage company wallets view:company-bank-account: View company bank accounts manage:company-bank-account: Create and manage company bank accounts manage:company-users: Manage company users ````