DOCSEARCHbyAlgolia
Submit Docs

Avenia API Integration Guide

website·Indexed 33 days ago

https://integration-guide.avenia.io/

Technical documentation for the Avenia API, covering account management, KYB/KYC verification, and fiat-to-crypto operations. Includes guides for managing subaccounts, beneficiary wallets, and bank account registrations for BRL, USD, MXN, COP, and EUR. Detailed references for Quotes and Tickets lifecycles, webhook authenticity verification, and migration paths from V1 to V2.

Tokens
84.2K
Snippets
395
Records
505
Agent score
61%

What's inside Avenia

  1. Overview of COP Beneficiary Payment Rails

    COP Beneficiaries support two different payment rails for Colombian Peso (COP) transactions. The rail used during payout is determined by the outputPaymentMethod specified in the quote:

    • PSE (Bank Transfer): Used for Colombian bank-to-bank transfers. Requires full bank details. Triggered when outputPaymentMethod=BANK-TRANSFER.
    • Bre-B: Used for transfers to any Bre-B-enabled Colombian bank using a key. Requires only a breBKey. Triggered when outputPaymentMethod=BRE-B.

    Critical Constraints:

    • Bre-B Cap: Transactions via Bre-B are limited to 3,000 USDC per leg. For payouts exceeding this amount, the beneficiary must have bank fields registered to route via PSE.
    • Irreversibility: COP transfers are irreversible once executed.
    • Sub-accounts: All endpoints support sub-accounts by passing the subAccountId as a request parameter.

  2. Overview of Avenia API Key Authentication

    Avenia API uses API Keys for authentication to provide a simpler alternative to JWT renewal flows. API Keys are linked to a specific user access, with a maximum limit of 5 API Keys per access. The system supports RSA, ECDSA, and Ed25519 cryptographic keys and allows IP restriction via CIDR (Classless Inter-Domain Routing).

  3. Overview of the asynchronous report lifecycle

    Statement and transaction reports are generated asynchronously. The process follows a three-step lifecycle: 1. Start a report generation job, 2. Poll the job status until it reaches 'success', and 3. Download the resulting file(s). Reports for large periods may be split into multiple parts and files. Job statuses include queued, running, success, and failed.
    POST   /v2/account/reports/{type}              → 202  { jobId, status: "running" }
GET    /v2/account/reports/{type}/{jobId}      → 200  { status, fileUrls, ... }   (poll until "success")
GET    /v2/account/reports/{type}/{jobId}/download?format=&part=   → 302 redirect to presigned S3 URL
GET    /v2/account/reports/{type}              → 200  { reports: [...] }           (list past jobs)

  4. Overview of EUR Beneficiary Bank Accounts

    EUR Bank Accounts are used as destination accounts for off-ramping to EUR fiat via SEPA transfers. To receive funds, a bank account must first be registered as a beneficiary and then referenced in tickets sending EUR.

    Critical Constraint: Use SEPA only for these accounts. If funds are sent via SWIFT to a EUR beneficiary registered here, the payment cannot be processed or tracked. For SWIFT payouts, use a SWIFT beneficiary instead.

  5. Integration Builder v2 Architecture and Project Structure

    The Integration Builder v2 is organized into a modular architecture separating the UI (React Flow canvas), the execution engine, and a data-driven registry for configurations.
    src/
├── pages/integration-builder.tsx      # Page shell and layout
├── components/builder/
│   ├── Canvas.tsx                      # React Flow canvas wrapper
│   ├── Sidebar.tsx                     # Collapsible block palette
│   ├── nodes/                          # BaseNode, CollapsedNode, ExpandedNode
│   ├── edges/                          # AnimatedEdge (particle effects)
│   ├── config/                         # NodeConfigPanel (inline forms)
│   ├── report/                         # ReportModal, ReportPreview, CodeTab, ExportActions
│   └── validation/                     # FlowValidator (real-time warnings)
├── engine/
│   ├── FlowEngine.ts                   # Dependency resolution and flow validation
│   ├── CodeGenerator.ts                # Generates cURL, Node, Python, Go snippets
│   ├── MarkdownGenerator.ts            # Generates markdown reports
│   └── BindingResolver.ts              # Auto-detects compatible output→input pairs
├── registry/                          # BlockRegistry (loads JSON config files)
├── store/useBuilderStore.ts            # Zustand store for nodes, edges, and state
├── hooks/                              # useAutoBinding, useFlowValidation, useCanvasExport, useTheme
└── configs/                            # JSON definitions for currencies, payment-methods, chains, and blocks

  7. Retrieve a specific KYC attempt by ID

    Get detailed information about a specific KYC attempt using its unique ID. This includes the submitted user data and the final result.

    Key Response Fields:

    • submissionData: Object containing user-submitted data (e.g., fullName, dateOfBirth, taxIdNumber).
    • status: Processing status (PENDING, PROCESSING, COMPLETED, EXPIRED).
    • result: Final outcome (APPROVED or REJECTED).
    • resultMessage: Human-readable details, especially for rejections.
    • rejectionLabels: Machine-readable labels for programmatic handling of rejection reasons.
    • retryable: Boolean indicating if the user is permitted to attempt this KYC level again.
    GET https://api.sandbox.avenia.io:10952/v2/kyc/attempts/{attemptId}

  8. Manage EUR Beneficiary Bank Accounts for SEPA Transfers

    The Avenia API allows the management of EUR bank accounts used as destination accounts for SEPA transfers. When creating output tickets to off-ramp EUR to a bank via the SEPA network, use the beneficiaryEurBankAccountId returned during the account registration process.

    Critical Constraint: Beneficiaries registered via this method are always paid over SEPA. Ensure the receiving bank supports SEPA. For EUR transfers over the SWIFT network, a different beneficiary registration process must be used (refer to the SWIFT Bank Guide).

  9. Simulate USD payouts in Sandbox

    Crypto to USD payouts are simulated in the sandbox environment and typically settle in about one minute. No real funds leave the account. To simulate a payout, you must first register a USD beneficiary and then create a ticket referencing that beneficiary's ID.
    # 1. Register a USD beneficiary
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "my-usd-account",
    "bankAccountNumber": "12345678901",
    "bankRoutingNumber": "021000021",
    "bankBeneficiaryName": "Jane Doe",
    "bankName": "JPMorgan Chase",
    "beneficiaryAddress": {
      "streetLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "USA"
    }
  }'

# 2. Create the payout ticket
# Use a quote with inputCurrency=USDC, inputPaymentMethod=INTERNAL, outputCurrency=USD, outputPaymentMethod=WIRE
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteToken": "QUOTE_TOKEN",
    "ticketUsdOutput": {
      "beneficiaryUsdBankAccountId": "BENEFICIARY_ID_FROM_STEP_1"
    }
  }'

  10. Get PIX key or BR Code ownership information

    Retrieve information about the owner of a PIX key (CPF, email, phone) or a BR Code. This endpoint provides the account holder's name, masked tax ID, and the bank's ISPB code. The ISPB code can be used to cross-check against blocked institutions before creating pay-out tickets.
    # pixKey: The BrCode or Pix Key to query
# decodePixKey: Set to true to collect more information if a pixKey is provided
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/pix-info?pixKey=00000000000&decodePixKey=true" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_TOKEN>"

  11. Integration Builder v2 Overview

    The Integration Builder v2 is a no-code drag-and-drop canvas builder powered by React Flow. It replaces the previous form-wizard approach with a visual flow editor (similar to n8n or Langflow) where developers compose API integration flows by dragging blocks, connecting them, and configuring parameters inline. The system generates executable code and markdown reports once a valid flow is constructed.

  12. Understand the Avenia Quote and Ticket transaction flow

    Transactions in Avenia follow a two-step process: first obtaining a Quote to determine pricing and validity, and then creating a Ticket to execute the transaction.

    1. Quote Phase: The user sends transaction parameters. The system calculates the price, fees, and validity, returning a quoteToken.
    2. Ticket Phase: The user creates a ticket using the quoteToken and specific execution parameters. The system processes the transaction and the user monitors the status until completion.