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

# Create order

> Unified order creation for onramp, offramp, and swap. Provide `quote_id` from a reserved quote, or `from`/`to` legs directly.

**Recipient rules:**
- Offramp: `institution_code`, `account_number`, `account_name`
- Onramp and swap: `address` (optional on-chain `memo`)

**Auth:** Secret key + HMAC. Account must be KYB-approved.

**Best practice:** Pass `quote_id` to lock pricing. Use a unique `merchant_reference` so you can correlate retries on your side.




## OpenAPI

````yaml /openapi/partner-api.yaml post /v1/orders
openapi: 3.1.0
info:
  title: Liquidramp Partner API
  version: 2.0.0
  license:
    name: Proprietary
  description: >
    Public integration API for consumer partners: reference data, exchange
    rates, quotes, orders, and webhooks.


    ## Authentication


    - **Public key (`pk_*`)**: read requests (reference data, rate preview) — no
    HMAC

    - **Secret key (`sk_*`)**: backend only — reads and writes (quotes, orders,
    fulfilment). Every `sk_*` request requires HMAC signing with your `enc_*`
    encryption key


    Create keys in the [partner portal](https://dashboard.liquidramp.com). Never
    send `enc_*` as a Bearer token. Never use `sk_*` or `enc_*` in client-side
    code.


    ## HMAC canonical string


    `clientId|timestamp|METHOD|path|rawBody`


    Path includes the `/v1` prefix and any query string. Signature: `sha256=` +
    HMAC-SHA256(canonical, `enc_*`).
servers:
  - url: https://vibe-api.liquidramp.com
    description: Test
  - url: https://api.liquidramp.com
    description: Live
security: []
tags:
  - name: Health
    description: Service health checks
  - name: Reference
    description: Institutions, networks, currencies, and account lookup
  - name: Exchange Rates
    description: Market rates and quote preview
  - name: Orders
    description: Quotes, order creation, fulfilment, and management
  - name: Webhooks
    description: Outbound order lifecycle events delivered to your server
paths:
  /v1/orders:
    post:
      tags:
        - Orders
      summary: Create order
      description: >
        Unified order creation for onramp, offramp, and swap. Provide `quote_id`
        from a reserved quote, or `from`/`to` legs directly.


        **Recipient rules:**

        - Offramp: `institution_code`, `account_number`, `account_name`

        - Onramp and swap: `address` (optional on-chain `memo`)


        **Auth:** Secret key + HMAC. Account must be KYB-approved.


        **Best practice:** Pass `quote_id` to lock pricing. Use a unique
        `merchant_reference` so you can correlate retries on your side.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              onramp:
                value:
                  quote_id: qte_abc123
                  merchant_reference: merchant-ref-001
                  recipient:
                    address: '0x34DF48981ce4d1899a2b1139CC0fDDb6951C4053'
                  customer:
                    reference: cust-001
                    name: Jane Doe
                    email: jane@example.com
                    phone: '+2348012345678'
                  metadata:
                    source: api
              offramp:
                value:
                  quote_id: qte_abc123
                  merchant_reference: merchant-ref-002
                  recipient:
                    institution_code: '000004'
                    account_number: '0123456789'
                    account_name: Jane Doe
                  customer:
                    reference: cust-001
                    name: Jane Doe
                    email: jane@example.com
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderDetail'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
        - SecretKeyHmac: []
components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - recipient
        - customer
      properties:
        quote_id:
          type: string
        merchant_reference:
          type: string
        from:
          $ref: '#/components/schemas/QuoteRequestLeg'
        to:
          $ref: '#/components/schemas/QuoteRequestLeg'
        recipient:
          oneOf:
            - $ref: '#/components/schemas/FiatRecipient'
            - $ref: '#/components/schemas/CryptoRecipient'
        refund:
          oneOf:
            - $ref: '#/components/schemas/FiatRecipient'
            - $ref: '#/components/schemas/CryptoRecipient'
        customer:
          $ref: '#/components/schemas/Customer'
        partner_fee:
          type: number
        provider_id:
          type: integer
        metadata:
          type: object
          additionalProperties: true
        memo:
          type: string
    SuccessEnvelope:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: boolean
          const: true
        message:
          type: string
        data: {}
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    OrderDetail:
      allOf:
        - $ref: '#/components/schemas/OrderList'
        - type: object
          properties:
            recipient:
              oneOf:
                - $ref: '#/components/schemas/FiatRecipient'
                - $ref: '#/components/schemas/CryptoRecipientResult'
            payin:
              oneOf:
                - $ref: '#/components/schemas/FiatPayin'
                - $ref: '#/components/schemas/CryptoPayin'
            payout:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/FiatPayout'
                  - $ref: '#/components/schemas/CryptoPayout'
            refund:
              oneOf:
                - $ref: '#/components/schemas/FiatRefund'
                - $ref: '#/components/schemas/CryptoRefund'
            timeline:
              type: array
              items:
                $ref: '#/components/schemas/TimelineEntry'
    QuoteRequestLeg:
      type: object
      properties:
        currency:
          type: string
          description: Asset code (fiat or crypto), e.g. NGN or USDT
        network:
          type: string
          description: Required for crypto currencies; omit for fiat
        amount:
          type: number
          exclusiveMinimum: 0
    FiatRecipient:
      type: object
      required:
        - institution_code
        - account_number
        - account_name
      properties:
        institution_code:
          type: string
        account_number:
          type: string
        account_name:
          type: string
        memo:
          type: string
    CryptoRecipient:
      type: object
      required:
        - address
      properties:
        address:
          type: string
        memo:
          type: string
    Customer:
      type: object
      required:
        - reference
        - name
        - email
      properties:
        reference:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        dob:
          type: string
          pattern: ^\d{2}-\d{2}-\d{4}$
          description: DD-MM-YYYY
        address:
          type: string
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        last_page:
          type: integer
    OrderList:
      type: object
      properties:
        reference:
          type: string
        merchant_reference:
          type:
            - string
            - 'null'
        customer_reference:
          type:
            - string
            - 'null'
        type:
          $ref: '#/components/schemas/OrderType'
        from:
          $ref: '#/components/schemas/OrderLeg'
        to:
          $ref: '#/components/schemas/OrderLeg'
        pricing:
          $ref: '#/components/schemas/OrderPricing'
        fee:
          $ref: '#/components/schemas/OrderFee'
        metadata:
          type:
            - object
            - 'null'
        amount_paid:
          type: number
        amount_settled:
          type: number
        amount_refunded:
          type: number
        percentage_settled:
          type: number
        status:
          $ref: '#/components/schemas/OrderStatus'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CryptoRecipientResult:
      type: object
      properties:
        network:
          type: string
        address:
          type: string
        memo:
          type: string
    FiatPayin:
      type: object
      properties:
        currency:
          type: string
        account_name:
          type: string
        account_number:
          type: string
        institution_code:
          type: string
        amount:
          type: number
        tx_reference:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
    CryptoPayin:
      type: object
      properties:
        asset:
          type: string
        address:
          type: string
        network:
          type: string
        amount:
          type: number
        tx_hash:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
    FiatPayout:
      type: object
      properties:
        currency:
          type: string
        account_name:
          type: string
        account_number:
          type: string
        institution_code:
          type: string
        amount:
          type: number
        percentage:
          type:
            - number
            - 'null'
        tx_reference:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
    CryptoPayout:
      type: object
      properties:
        asset:
          type: string
        address:
          type: string
        network:
          type: string
        amount:
          type: number
        percentage:
          type:
            - number
            - 'null'
        tx_hash:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
    FiatRefund:
      type: object
      properties:
        currency:
          type: string
        account_name:
          type: string
        account_number:
          type: string
        institution_code:
          type: string
        amount:
          type: number
        tx_reference:
          type:
            - string
            - 'null'
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
    CryptoRefund:
      type: object
      properties:
        asset:
          type: string
        address:
          type: string
        network:
          type: string
        amount:
          type: number
        tx_hash:
          type:
            - string
            - 'null'
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
    TimelineEntry:
      type: object
      properties:
        group:
          type: string
        event:
          type: string
        details: {}
        created_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: boolean
          const: false
        code:
          type: string
          enum:
            - E_BADREQUEST
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_NOTFOUND
            - E_CONFLICT
            - E_VALIDATION_ERROR
            - E_RATE_LIMITED
            - E_IP_BLOCKED
        message:
          type: string
    OrderType:
      type: string
      enum:
        - onramp
        - offramp
        - swap
    OrderLeg:
      type: object
      properties:
        currency:
          type: string
        network:
          type: string
        amount:
          type: number
    OrderPricing:
      type: object
      properties:
        base_currency:
          type: string
        quote_currency:
          type: string
        exchange_rate:
          type: number
    OrderFee:
      type: object
      properties:
        currency:
          type: string
        network_fee:
          type: number
        protocol_fee:
          type: number
        partner_fee:
          type: number
        vat:
          type: number
        total:
          type: number
        fee_in_rate:
          type: boolean
      description: >-
        Omitted from responses when the fee is already embedded in
        `pricing.exchange_rate`.
    OrderStatus:
      type: string
      enum:
        - initiated
        - pending
        - processing
        - settled
        - awaiting_user_payment
        - awaiting_lp_payment
        - routing
        - executing
        - partially_completed
        - completed
        - cancelled
        - expired
        - failed
        - refunded
        - reverted
  responses:
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            status: false
            code: E_VALIDATION_ERROR
            message: 'recipient: recipient is required'
  securitySchemes:
    SecretKeyHmac:
      type: http
      scheme: bearer
      description: |
        Bearer sk_* plus required headers:
        - liquidramp-client-id
        - liquidramp-timestamp (unix ms)
        - liquidramp-signature (sha256=...)

````