> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tender.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate On-ramp

> Create an on-ramp request using a valid quote

<Note>
  **Auth method: Signed (HMAC)** — this endpoint requires the full set of signed
  headers: `x-access-id`, `x-request-id`, `x-timestamp`, and an HMAC-SHA256
  `authorization` signature. See [Authentication](/api-reference/authentication#signed-hmac-authentication).
</Note>

## Headers

<ParamField header="authorization" type="string" required>
  Base64-encoded HMAC-SHA256 signature of the request payload using your API secret

  **Example:** `"5e73d044c44d733fcf819ad3409aaa..."`
</ParamField>

<ParamField header="x-timestamp" type="string" required>
  **Example:** `"2025-03-15T09:45:53.000Z"`
</ParamField>

<ParamField header="x-request-id" type="string" required>
  **Example:** `"550e8400-e29b-41d4-a716-446655440000"`
</ParamField>

<ParamField header="x-access-id" type="string" required>
  **Example:** `"your-access-id-here"`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  **Example:** `"application/json"`
</ParamField>

## Body

<ParamField body="quoteId" type="string" required>
  The `quoteId` returned by [Get On-ramp Quote](/api-reference/endpoint/onramp/quote). Must not be
  expired or already used. Each quote is single-use.

  **Example:** `"b7f2a1c3-9d4e-4b2f-a8c0-1e2d3f4a5b6c"`
</ParamField>

<ParamField body="targetAddress" type="string" required>
  Wallet address that will receive the crypto. Must be valid for the chain specified in the quote.

  **Example:** `"TRDFGhjkytywooiueonuoo"`
</ParamField>

<ParamField body="customer" type="object" required>
  Details of the customer making the fiat payment

  <Expandable title="customer properties">
    <ParamField body="email" type="string" required>
      Customer email address

      **Example:** `"customer@example.com"`
    </ParamField>

    <ParamField body="name" type="string" required>
      Customer full name

      **Example:** `"Ada Obi"`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Optional key-value pairs for your own reference. Values must be strings or numbers.

  **Example:** `{ "orderId": "ORD-9821", "userId": "usr_42" }`
</ParamField>

## Error cases

| Condition                           | Message                             |
| ----------------------------------- | ----------------------------------- |
| `quoteId` not found or already used | `"Quote not found or already used"` |
| Quote past its `expiresAt`          | `"Quote has expired"`               |
| Missing `quoteId` field             | Joi 400 validation error            |

## Response

<ResponseField name="status" type="string" required>
  **Example:** `"success"`
</ResponseField>

<ResponseField name="message" type="string" required>
  **Example:** `"Onramp initiated"`
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="data properties">
    <ResponseField name="reference" type="string">
      Unique reference for this on-ramp request. Use this to poll status.

      **Example:** `"a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d"`
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial status — always `pending_payment`

      **Example:** `"pending_payment"`
    </ResponseField>

    <ResponseField name="bankTransfer" type="object">
      Virtual bank account the customer must pay into

      <Expandable title="bankTransfer properties">
        <ResponseField name="accountNumber" type="string">
          **Example:** `"0123456789"`
        </ResponseField>

        <ResponseField name="accountName" type="string">
          **Example:** `"Tender / Ada Obi"`
        </ResponseField>

        <ResponseField name="bankName" type="string">
          **Example:** `"Wema Bank"`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      ISO 8601 timestamp after which the virtual bank account expires (1 hour)

      **Example:** `"2025-06-10T11:00:00.000Z"`
    </ResponseField>

    <ResponseField name="amount" type="object">
      <Expandable title="amount properties">
        <ResponseField name="value" type="number">
          Fiat amount the customer must pay (from the quote)

          **Example:** `50000`
        </ResponseField>

        <ResponseField name="currency" type="string">
          Fiat currency (from the quote)

          **Example:** `"NGN"`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="targetChain" type="string">
      **Example:** `"tron"`
    </ResponseField>

    <ResponseField name="targetAddress" type="string">
      **Example:** `"TRDFGhjkytywooiueonuoo"`
    </ResponseField>

    <ResponseField name="targetCurrency" type="string">
      **Example:** `"USDT"`
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml POST /v1/api/onramp/initiate
openapi: 3.1.0
info:
  title: Tender API
  description: Tender Developer API for cryptocurrency payments and agent management
  version: 1.0.0
  contact:
    name: Tender Support
    url: https://tender.cash
servers:
  - url: https://secureapi.tender.cash
    description: Production Server
  - url: https://sandbox-api.tender.cash
    description: Sandbox Server
security:
  - SignedAuth: []
tags:
  - name: Agents
    description: Manage agents and sub-businesses
  - name: Transactions
    description: Payment and transaction operations
  - name: System
    description: System information and configuration
  - name: Webhooks
    description: Webhook management and logs
  - name: On-ramp
    description: Fiat-to-crypto on-ramp operations
  - name: Payouts
    description: Send crypto from merchant balance to a wallet address or payout account
  - name: Subwallets
    description: Provision and manage crypto wallet infrastructure for your end-users
paths:
  /v1/api/onramp/initiate:
    post:
      tags:
        - On-ramp
      summary: Initiate On-ramp
      description: >-
        Convert a fiat payment into crypto and deliver it to a target wallet
        address. Returns a virtual bank account for the customer to pay into.
      operationId: initiateOnramp
      parameters:
        - name: authorization
          in: header
          required: true
          description: >-
            Base64-encoded HMAC-SHA256 signature of the request payload using
            the API secret
          schema:
            type: string
        - name: x-timestamp
          in: header
          required: true
          description: Current timestamp in ISO 8601 format
          schema:
            type: string
            format: date-time
          example: '2025-03-15T09:45:53.000Z'
        - name: x-request-id
          in: header
          required: true
          description: Unique identifier for the request (UUID v4)
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-access-id
          in: header
          required: true
          description: Your API access ID provided by Tender
          schema:
            type: string
          example: your-access-id-here
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
          example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateOnrampRequest'
            example:
              quoteId: b7f2a1c3-9d4e-4b2f-a8c0-1e2d3f4a5b6c
              targetAddress: TRDFGhjkytywooiueonuoo
              customer:
                email: customer@example.com
                name: Ada Obi
              metadata:
                orderId: ORD-9821
      responses:
        '200':
          description: On-ramp initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateOnrampResponse'
              example:
                status: success
                message: Onramp initiated
                data:
                  reference: a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d
                  status: pending_payment
                  bankTransfer:
                    accountNumber: '0123456789'
                    accountName: Tender / Ada Obi
                    bankName: Wema Bank
                  expiresAt: '2025-06-09T11:00:00.000Z'
                  amount:
                    value: 50000
                    currency: NGN
                  targetChain: tron
                  targetAddress: TRDFGhjkytywooiueonuoo
                  targetCurrency: USDT
        '400':
          description: >-
            Validation error — unsupported currency, amount below minimum, or
            missing fields
      security:
        - SignedAuth: []
components:
  schemas:
    InitiateOnrampRequest:
      type: object
      required:
        - quoteId
        - targetAddress
        - customer
      properties:
        quoteId:
          type: string
          format: uuid
          example: b7f2a1c3-9d4e-4b2f-a8c0-1e2d3f4a5b6c
        targetAddress:
          type: string
          example: TRDFGhjkytywooiueonuoo
        customer:
          type: object
          required:
            - email
            - name
          properties:
            email:
              type: string
              format: email
              example: customer@example.com
            name:
              type: string
              example: Ada Obi
        metadata:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
    InitiateOnrampResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            reference:
              type: string
              format: uuid
            status:
              type: string
              example: pending_payment
            bankTransfer:
              type: object
              properties:
                accountNumber:
                  type: string
                accountName:
                  type: string
                bankName:
                  type: string
            expiresAt:
              type: string
              format: date-time
            amount:
              type: object
              properties:
                value:
                  type: number
                currency:
                  type: string
            targetChain:
              type: string
            targetAddress:
              type: string
            targetCurrency:
              type: string
  securitySchemes:
    SignedAuth:
      type: apiKey
      in: header
      name: authorization
      description: >-
        Signed (HMAC) authentication. Required headers: x-access-id,
        x-request-id (UUID v4), x-timestamp (ISO 8601), and authorization
        (Base64 HMAC-SHA256 signature of {timeStamp, requestId, accessId} using
        your access secret).

````