---
updatedAt: 2026-04-30T12:30:05.000Z
agentTools:
  projectIndex: https://c-vmch.readme.io/llms.txt
---

# Get a specific request

Retrieve details of a specific request by ID

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "paths": {
    "/requests/{id}": {
      "get": {
        "description": "Retrieve details of a specific request by ID",
        "operationId": "RequestsController_getRequest",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Request ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Request found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestResponseDto"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "404": {
            "description": "Request not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "aggregator-api-key": []
          }
        ],
        "summary": "Get a specific request",
        "tags": [
          "Aggregator Requests"
        ]
      }
    }
  },
  "info": {
    "title": "Protocol API",
    "description": "## Overview\nCentiiv Protocol is a decentralized liquidity aggregation platform for fiat-to-crypto and crypto-to-fiat conversions. This API enables aggregators, liquidity providers, and applications to integrate with the protocol.\n\n---\n\n## Environments\n\n| Environment | API Key Prefix | Use Case |\n|-------------|----------------|----------|\n| **Sandbox** | `sandbox_*` | Testing and development |\n| **Live** | `live_*` | Production transactions |\n\nThe environment is automatically determined from your API key prefix. You can also override it using the `X-Environment` header.\n\n---\n\n## Authentication Methods\n\n### 1. JWT Bearer Token\nFor dashboard access and management endpoints\n### 2. Aggregator API Key\nFor quote and order endpoints:\n- Header: `X-API-Key: <your-api-key>` (Format: `pk_...` or `sk_...`)\n---\n\n## Transaction Types\n\n### Offramp (Stablecoin → Fiat)\nUser sends crypto, receives fiat to their bank account.\n\n### Onramp (Fiat → Stablecoin)\nUser deposits fiat to virtual account, receives crypto to their wallet.\n\n---\n\n## Fee Structure\n\n| Fee Type | Description | Example |\n|----------|-------------|--------|\n| **PERCENTAGE** | Percentage of transaction amount | 1.5% fee on 1500 rate → 1477.5 effective rate |\n| **SPREAD** | Fixed amount subtracted from rate | 10 spread on 1500 rate → 1490 effective rate |\n| **FIXED** | Flat fee per transaction | $5 fixed fee deducted from output |\n\n",
    "version": "1.0.0",
    "contact": {}
  },
  "servers": [
    {
      "url": "https://api.centiiv.io",
      "description": "Production"
    },
    {
      "url": "https://api.staging.centiiv.io",
      "description": "Staging"
    }
  ],
  "components": {
    "securitySchemes": {
      "aggregator-api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Aggregator API key. Format: `pk_ENV_xxx` or `sk_ENV_xxx`. Where `ENV` is either `sandbox` or `live`"
      },
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "type": "http",
        "description": "JWT access token."
      }
    },
    "schemas": {
      "BeneficiaryResponseDto": {
        "type": "object",
        "properties": {
          "accountName": {
            "type": "object",
            "description": "Account holder name"
          },
          "accountNumber": {
            "type": "object",
            "description": "Bank account number"
          },
          "bankCode": {
            "type": "object",
            "description": "Bank code"
          },
          "bankName": {
            "type": "object",
            "description": "Bank name"
          },
          "address": {
            "type": "object",
            "description": "Beneficiary wallet address (onramp)"
          },
          "network": {
            "type": "object",
            "description": "Blockchain network (onramp)"
          },
          "isTestnet": {
            "type": "object",
            "description": "Whether this is testnet (onramp)"
          }
        }
      },
      "TemporaryWalletResponseDto": {
        "type": "object",
        "properties": {
          "publicAddress": {
            "type": "string",
            "description": "Deposit address of the temporary wallet - OFFRAMP (Crypto→Fiat): User deposits crypto here. For proxy-chain offramps this is the proxy-chain EOA where deposits are detected (e.g. Polygon/Arbitrum/Base); see underlyingWalletAddress for the settlement wallet it forwards to. ONRAMP (Fiat→Crypto): Not included in response, user deposits to virtual account instead."
          },
          "network": {
            "type": "string",
            "description": "Blockchain network of the deposit wallet. For proxy-chain offramps this is the proxy chain (where the user deposits); the settlement chain is underlyingWalletNetwork."
          },
          "underlyingWalletAddress": {
            "type": "string",
            "description": "Underlying settlement wallet address — present only when publicAddress is a proxy-chain EOA that forwards deposits to it."
          },
          "underlyingWalletNetwork": {
            "type": "string",
            "description": "Chain of the underlying settlement wallet; differs from network only for proxy-chain offramps."
          },
          "isTestnet": {
            "type": "boolean",
            "description": "Whether this is a testnet or mainnet address"
          },
          "expiresAt": {
            "format": "date-time",
            "type": "string",
            "description": "Expiration time of the temporary wallet"
          },
          "virtualAccountNumber": {
            "type": "string",
            "description": "Virtual account number for fiat deposits - ONRAMP (Fiat→Crypto): User deposits NGN here. OFFRAMP (Crypto→Fiat): Not included in response."
          },
          "virtualAccountName": {
            "type": "string",
            "description": "Virtual account holder name - ONRAMP (Fiat→Crypto): Account name for user to deposit to. OFFRAMP (Crypto→Fiat): Not included in response."
          },
          "virtualBankName": {
            "type": "string",
            "description": "Virtual account bank name - ONRAMP (Fiat→Crypto): Bank name where virtual account is hosted. OFFRAMP (Crypto→Fiat): Not included in response."
          },
          "virtualBankCode": {
            "type": "string"
          },
          "accountName": {
            "type": "string"
          },
          "accountNumber": {
            "type": "string"
          },
          "bankCode": {
            "type": "string"
          },
          "bankName": {
            "type": "string"
          },
          "depositedAt": {
            "type": "string"
          },
          "depositNarration": {
            "type": "string"
          },
          "disbursedAt": {
            "type": "string"
          },
          "disbursementReferences": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mobileMoney": {
            "type": "object",
            "description": "Mobile-money collection details (KES onramp only). Present instead of virtual-account fields when the deposit is pulled from the depositor MPESA account."
          }
        }
      },
      "BlockchainTransactionDto": {
        "type": "object",
        "properties": {
          "txHash": {
            "type": "string",
            "description": "Transaction hash for blockchain explorer"
          },
          "direction": {
            "type": "string",
            "enum": [
              "INCOMING",
              "OUTGOING"
            ],
            "description": "Direction of the transaction (IN or OUT)"
          },
          "amount": {
            "type": "string",
            "description": "Transaction amount"
          },
          "network": {
            "type": "string",
            "enum": [
              "STELLAR",
              "SOLANA",
              "ARC",
              "BASE",
              "ARBITRUM",
              "OPTIMISM",
              "POLYGON",
              "AVALANCHE",
              "APTOS",
              "ETHEREUM",
              "BSC",
              "HYPEREVM"
            ],
            "description": "Blockchain network"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "CONFIRMED",
              "FAILED"
            ],
            "description": "Transaction status"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Transaction creation timestamp"
          }
        },
        "required": [
          "txHash",
          "direction",
          "amount",
          "network",
          "status",
          "createdAt"
        ]
      },
      "RequestResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "PROCESSING",
              "FULFILLED",
              "FAILED",
              "EXPIRED",
              "REFUNDED",
              "CANCELLED"
            ],
            "description": "Current status of the request"
          },
          "environment": {
            "type": "string",
            "enum": [
              "LIVE",
              "SANDBOX"
            ]
          },
          "fromAsset": {
            "type": "string",
            "enum": [
              "USDC",
              "EURC",
              "USDT",
              "CNGN",
              "USDT0"
            ]
          },
          "toAsset": {
            "type": "string",
            "enum": [
              "NGN",
              "CNY",
              "UGX",
              "KES",
              "GHS",
              "USD",
              "XAF",
              "XOF",
              "CDF",
              "ETB",
              "ZAR",
              "TZS",
              "RWF"
            ]
          },
          "amount": {
            "type": "number"
          },
          "totalToPay": {
            "type": "number",
            "description": "Total the payer must transfer to fund the request. Equals `amount` when the aggregator fee mode is DEDUCTED (fee taken from the output); `amount + fee` when the fee mode is ADDED (fee charged on top).",
            "example": 1.005
          },
          "type": {
            "type": "string",
            "enum": [
              "ONRAMP",
              "OFFRAMP"
            ],
            "description": "Type of transaction: ONRAMP (Fiat→Crypto) or OFFRAMP (Crypto→Fiat)"
          },
          "beneficiary": {
            "description": "Beneficiary information for offramp transactions",
            "allOf": [
              {
                "$ref": "#/components/schemas/BeneficiaryResponseDto"
              }
            ]
          },
          "description": {
            "type": "string"
          },
          "estimatedSettleTime": {
            "type": "number"
          },
          "temporaryWallet": {
            "$ref": "#/components/schemas/TemporaryWalletResponseDto"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "blockchainTxs": {
            "description": "Blockchain transactions associated with this request",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockchainTransactionDto"
            }
          },
          "metadata": {
            "type": "object",
            "description": "Additional transaction metadata. For ONRAMP, contains sessionId, reference, and sender information."
          },
          "adminNote": {
            "type": "object",
            "nullable": true
          },
          "aggregator": {
            "type": "object",
            "description": "Aggregator info for this request"
          },
          "fulfillments": {
            "description": "Fulfillment disbursal details reported by the LP node",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "status",
          "environment",
          "fromAsset",
          "toAsset",
          "amount",
          "totalToPay",
          "type",
          "createdAt",
          "updatedAt"
        ]
      },
      "ErrorResponseDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "error": {
            "type": "string",
            "example": "BAD_REQUEST",
            "enum": [
              "BAD_REQUEST",
              "UNAUTHORIZED",
              "FORBIDDEN",
              "NOT_FOUND",
              "CONFLICT",
              "UNPROCESSABLE_ENTITY",
              "TOO_MANY_REQUESTS",
              "INTERNAL_SERVER_ERROR",
              "BAD_GATEWAY",
              "GATEWAY_TIMEOUT"
            ]
          },
          "message": {
            "type": "string",
            "example": "Validation failed"
          },
          "details": {
            "example": [
              "amount must be a positive number",
              "currency must be a valid ISO code"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requestId": {
            "type": "string",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "timestamp": {
            "type": "string",
            "example": "2026-04-17T10:00:00.000Z"
          },
          "path": {
            "type": "string",
            "example": "/requests"
          }
        },
        "required": [
          "success",
          "statusCode",
          "error",
          "message",
          "timestamp",
          "path"
        ]
      }
    }
  }
}
```