# On-Ramp (Fiat → Crypto)

**Flow:** lock a quote → receive fiat payment instructions → user deposits fiat → crypto sent to wallet.

### Create on-ramp transfer

<mark style="color:$success;">`POST`</mark>  :  `/api/v1/on-ramp`

Lock a valid `ON_RAMP` quote and generate fiat payment instructions.

**Required scopes:** `transfers:write` or `all`

{% hint style="info" %}
&#x20;This endpoint supports idempotency. Include an `Idempotency-Key` header to prevent duplicate transfers.
{% endhint %}

**Request body**

<table><thead><tr><th width="231">Parameter</th><th width="101">Type</th><th width="115">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>quoteId</code></td><td>UUID</td><td>Required</td><td>ID of a valid, non-expired <code>ON_RAMP</code> quote</td></tr><tr><td><code>recipientId</code></td><td>UUID</td><td>Required</td><td>UUID of the approved recipient</td></tr><tr><td><code>destinationWalletAddress</code></td><td>string</td><td>Required</td><td>Wallet address to receive crypto (e.g. Solana addr)</td></tr><tr><td><code>clientReference</code></td><td>string</td><td>Optional</td><td>Your internal reference (max 128 chars)</td></tr></tbody></table>

&#x20;CURL REQUEST

```bash
curl -X POST https://zynta-lastmile-api.up.railway.app/api/v1/on-ramp \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onramp-001" \
  -d '{
    "quoteId": "770a3500-f30c-42e5-b827-557766551111",
    "recipientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "destinationWalletAddress": "GqN8vW7Qxz4F9kP2mR5tY8uI3oP6aS9dF1gH4jK7lM0n"
  }'
```

**Response `201 Created`**

```json
{
  "onRampId": "770g3500-f30c-52e5-b827-557766551111",
  "state": "PENDING_DEPOSIT",
  "destinationWalletAddress": "GqN8vW7Qxz4F9kP2mR5tY8uI3oP6aS9dF1gH4jK7lM0n",
  "fundingInstructions": {
    "accountNumber": "9876543210",
    "bankName": "Wema Bank",
    "accountName": "Zynta Technologies",
    "reference": "ZYNTA-REF-123",
    "amount": 1650000,
    "currency": "NGN",
    "expiresAt": "2026-03-24T14:15:00Z"
  },
  "createdAt": "2026-03-24T14:00:00Z"
}
```

The user must deposit the exact fiat amount to the provided bank account with the reference code before the expiry.

***

### Get on-ramp transfer

<mark style="color:blue;">`GET`</mark> :  `/api/v1/on-ramp/{id}`

Retrieve details of an existing on-ramp transfer.

**Required scopes:** `transfers:read` or `all`

***

### Get transfer timeline

<mark style="color:blue;">`GET`</mark> :  `/api/v1/on-ramp/{id}/timeline`

Returns the audit timeline and event history for a transfer.

***

### Response fields

| Field                      | Type     | Description                                                                                |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `onRampId`                 | UUID     | Unique on-ramp transfer identifier                                                         |
| `state`                    | string   | `QUOTE_LOCKED`, `PENDING_DEPOSIT`, `PROCESSING`, `COMPLETED`, `FAILED`, or `EXPIRED`       |
| `destinationWalletAddress` | string   | Wallet address receiving crypto                                                            |
| `fundingInstructions`      | object   | `accountNumber`, `bankName`, `accountName`, `reference`, `amount`, `currency`, `expiresAt` |
| `cryptoTxHash`             | string   | Blockchain transaction hash (populated on completion)                                      |
| `completedAt`              | datetime | Timestamp when transfer completed                                                          |
| `failureReason`            | string   | Reason for failure (if state is `FAILED`)                                                  |
| `createdAt`                | datetime | Transfer creation time                                                                     |
| `updatedAt`                | datetime | Last status update time                                                                    |

{% hint style="info" %}
The `cryptoTxHash` field is populated once the crypto has been sent to the destination wallet. Use it to verify the on-chain transaction.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zynta.com/api-reference/transfers/on-ramp-fiat-crypto.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.