> ## Documentation Index > Fetch the complete documentation index at: https://docs.compasslabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a fiat on-ramp payment + get the checkout link > Create a fiat on-ramp payment and return the browser-checkout handoff. A fiat card + identity-verification flow can only render in a browser, so this endpoint returns a **`checkout_url`** (a Compass-hosted page) together with `payment_id`, the one-time-wallet `deposit_address`, an initial `status`, and a `user_instructions` string. **How to drive this (CLI / MCP agent / UI):** 1. **Present `checkout_url` to the user and open it in a browser.** It renders the card payment + identity verification and delivers USDC on Ethereum to the destination wallet. (An MCP agent cannot open a browser itself — show the link and ask the user to open it.) 2. **Poll `GET /v2/onramp/status?payment_id=...`** until `status` becomes `delivered` (or `failed`). `pending` = awaiting payment, `processing` = payment received and bridging/swapping to USDC. 3. Once `delivered`, the USDC is in the user's own wallet — continue with the tokenized buy. Funds are never held by Compass: the `deposit_address` is a one-time wallet owned solely by the user's wallet. ## OpenAPI ````yaml /v2/combined_spec.json post /v2/onramp/create openapi: 3.1.0 info: title: Compass API description: Compass Labs DeFi API version: 0.0.1 servers: - url: https://api.compasslabs.ai description: Production server security: - ApiKeyAuth: [] paths: /v2/onramp/create: post: tags: - Onramp summary: Create a fiat on-ramp payment + get the checkout link description: >- Create a fiat on-ramp payment and return the browser-checkout handoff. A fiat card + identity-verification flow can only render in a browser, so this endpoint returns a **`checkout_url`** (a Compass-hosted page) together with `payment_id`, the one-time-wallet `deposit_address`, an initial `status`, and a `user_instructions` string. **How to drive this (CLI / MCP agent / UI):** 1. **Present `checkout_url` to the user and open it in a browser.** It renders the card payment + identity verification and delivers USDC on Ethereum to the destination wallet. (An MCP agent cannot open a browser itself — show the link and ask the user to open it.) 2. **Poll `GET /v2/onramp/status?payment_id=...`** until `status` becomes `delivered` (or `failed`). `pending` = awaiting payment, `processing` = payment received and bridging/swapping to USDC. 3. Once `delivered`, the USDC is in the user's own wallet — continue with the tokenized buy. Funds are never held by Compass: the `deposit_address` is a one-time wallet owned solely by the user's wallet. operationId: v2_onramp_create requestBody: content: application/json: schema: $ref: '#/components/schemas/OnrampCreateRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OnrampCreate' '400': description: '`INVALID_ONRAMP_REQUEST` — bad fiat amount or unsupported currency.' content: application/json: schema: $ref: '#/components/schemas/OnrampErrorResponse' '402': description: >- `KYC_REQUIRED` — identity verification is required; complete it in the hosted checkout (`checkout_url`). content: application/json: schema: $ref: '#/components/schemas/OnrampErrorResponse' '410': description: '`QUOTE_EXPIRED` — the quote is stale; re-quote and retry.' content: application/json: schema: $ref: '#/components/schemas/OnrampErrorResponse' '422': description: >- `UNSUPPORTED_ONRAMP_OUTPUT` — delivery is limited to USDC on Ethereum. content: application/json: schema: $ref: '#/components/schemas/OnrampErrorResponse' '502': description: '`HALLIDAY_API_UNAVAILABLE` — the on-ramp provider is unavailable.' content: application/json: schema: $ref: '#/components/schemas/OnrampErrorResponse' x-codeSamples: - lang: python label: Python (SDK) source: |- from compass_api_sdk import CompassAPI with CompassAPI( api_key_auth="", ) as compass_api: res = compass_api.onramp.onramp_create(fiat_amount="", destination_address="", fiat_currency="USD") # Handle response print(res) - lang: typescript label: Typescript (SDK) source: |- import { CompassApiSDK } from "@compass-labs/api-sdk"; const compassApiSDK = new CompassApiSDK({ apiKeyAuth: "", }); async function run() { const result = await compassApiSDK.onramp.onrampCreate({ fiatAmount: "", fiatCurrency: "USD", destinationAddress: "", }); console.log(result); } run(); components: schemas: OnrampCreateRequest: properties: fiat_amount: type: string title: Fiat Amount description: Amount of fiat to spend, as a decimal string (e.g. `100`). examples: - '100' fiat_currency: type: string title: Fiat Currency description: ISO-4217 fiat currency code. Defaults to `USD`. default: USD examples: - USD destination_address: type: string title: Destination Address description: >- The wallet that will receive the USDC on Ethereum. Funds are delivered here directly — Compass never holds them. examples: - '0x29F20a192328eF1aD35e1564aBFf4Be9C5ce5f7B' quote_id: anyOf: - type: string - type: 'null' title: Quote Id description: >- Optional Halliday quote handle to confirm against. Omit to confirm against a fresh quote derived from the amount and currency. type: object required: - fiat_amount - destination_address title: OnrampCreateRequest description: >- Create a fiat on-ramp payment delivering USDC on Ethereum. Carries the same fields as the quote (a quote is implicit — we do not persist a quote handle). ``quote_id`` is optional and only echoed upstream if Halliday's ``/payments/confirm`` requires a previously-issued quote handle; omit it to confirm against a fresh quote. OnrampCreate: properties: payment_id: type: string title: Payment Id description: Halliday's payment id. Use it to poll status. deposit_address: type: string title: Deposit Address description: >- The one-time-wallet (OTW) deposit address for this payment, owned solely by the user's wallet (non-custodial). checkout_url: type: string title: Checkout Url description: >- Compass-hosted checkout page to open in a browser. It renders the card + identity-verification flow and delivers USDC to the destination wallet. user_instructions: type: string title: User Instructions description: >- Short, agent-actionable guidance: open the checkout link, pay, then poll status until delivered. status: type: string enum: - pending - processing - delivered - failed title: Status description: Initial lifecycle state (typically `pending`). quote: $ref: '#/components/schemas/OnrampQuote' description: The resolved quote this payment was created against. type: object required: - payment_id - deposit_address - checkout_url - user_instructions - status - quote title: OnrampCreate description: >- A created on-ramp payment, with the browser-handoff affordances. The caller (CLI / MCP agent / UI) presents ``checkout_url`` to the user to pay by card and complete identity verification, then polls ``GET /v2/onramp/status`` until ``status`` is ``delivered``. OnrampErrorResponse: properties: error: type: string title: Error description: >- Short human-readable error label (e.g. `Payment not found.`, `On-ramp provider unavailable`, `Identity verification required`). message: type: string title: Message description: Human-readable explanation. type: object required: - error - message title: OnrampErrorResponse description: >- Standard error envelope returned by every non-2xx on-ramp response. Surfaced in OpenAPI ``responses`` declarations so SDK consumers can decode failures uniformly without inspecting per-status-code shapes. OnrampQuote: properties: fiat_amount: type: string title: Fiat Amount description: Fiat amount to spend. examples: - '100' fiat_currency: type: string title: Fiat Currency description: ISO-4217 fiat currency code. examples: - USD output_amount: type: string title: Output Amount description: Estimated USDC delivered, human-readable (6-decimal token). examples: - '98.50' output_asset: type: string const: USDC title: Output Asset description: Delivered asset. Always USDC for this on-ramp. default: USDC output_chain: type: string const: ethereum title: Output Chain description: Delivery chain. Always Ethereum for this on-ramp. default: ethereum exchange_rate: type: string title: Exchange Rate description: USDC received per unit of fiat. examples: - '0.985' fees: $ref: '#/components/schemas/OnrampFees' description: Fee breakdown. min_amount: anyOf: - type: string - type: 'null' title: Min Amount description: Minimum fiat amount accepted, if advertised by the provider. examples: - '20' max_amount: anyOf: - type: string - type: 'null' title: Max Amount description: Maximum fiat amount accepted, if advertised by the provider. examples: - '10000' expires_at: anyOf: - type: string - type: 'null' title: Expires At description: ISO-8601 timestamp after which this quote is stale, if any. type: object required: - fiat_amount - fiat_currency - output_amount - exchange_rate - fees title: OnrampQuote description: An indicative fiat -> USDC-on-Ethereum quote. OnrampFees: properties: provider_fee: type: string title: Provider Fee description: Fee charged by the on-ramp provider, in fiat. examples: - '2.99' network_fee: type: string title: Network Fee description: Estimated network/gas fee, in fiat. examples: - '0.50' business_fees: type: string title: Business Fees description: Compass business fee, in fiat. Always `0` for now. default: '0' examples: - '0' type: object required: - provider_fee - network_fee title: OnrampFees description: |- Fee breakdown for an on-ramp quote. ``business_fees`` is a fixed ``"0"`` for now — monetization is a single future lever and is intentionally not charged. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Compass API Key. Get your key [here](https://www.compasslabs.ai/dashboard). ````