Python (SDK)

from compass_api_sdk import CompassAPI


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.onramp.onramp_create(fiat_amount="<value>", destination_address="<value>", fiat_currency="USD")

    # Handle response
    print(res)

{
  "payment_id": "<string>",
  "deposit_address": "<string>",
  "checkout_url": "<string>",
  "user_instructions": "<string>",
  "quote": {
    "fiat_amount": "<string>",
    "fiat_currency": "<string>",
    "output_amount": "<string>",
    "exchange_rate": "<string>",
    "fees": {
      "provider_fee": "<string>",
      "network_fee": "<string>",
      "business_fees": "0"
    },
    "output_asset": "USDC",
    "output_chain": "ethereum",
    "min_amount": "20",
    "max_amount": "10000",
    "expires_at": "<string>"
  }
}

Onramp

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):

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.)
Poll GET /v2/onramp/status?payment_id=... until status becomes delivered (or failed). pending = awaiting payment, processing = payment received and bridging/swapping to USDC.
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.

POST

onramp

create

Python (SDK)

from compass_api_sdk import CompassAPI


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.onramp.onramp_create(fiat_amount="<value>", destination_address="<value>", fiat_currency="USD")

    # Handle response
    print(res)

{
  "payment_id": "<string>",
  "deposit_address": "<string>",
  "checkout_url": "<string>",
  "user_instructions": "<string>",
  "quote": {
    "fiat_amount": "<string>",
    "fiat_currency": "<string>",
    "output_amount": "<string>",
    "exchange_rate": "<string>",
    "fees": {
      "provider_fee": "<string>",
      "network_fee": "<string>",
      "business_fees": "0"
    },
    "output_asset": "USDC",
    "output_chain": "ethereum",
    "min_amount": "20",
    "max_amount": "10000",
    "expires_at": "<string>"
  }
}

Authorizations

x-api-key

string

header

required

Your Compass API Key. Get your key here.

Body

application/json

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.

fiat_amount

string

required

Amount of fiat to spend, as a decimal string (e.g. 100).

Example:

"100"

destination_address

string

required

The wallet that will receive the USDC on Ethereum. Funds are delivered here directly — Compass never holds them.

Example:

"0x29F20a192328eF1aD35e1564aBFf4Be9C5ce5f7B"

fiat_currency

string

default:USD

ISO-4217 fiat currency code. Defaults to USD.

Example:

"USD"

quote_id

string | null

Optional Halliday quote handle to confirm against. Omit to confirm against a fresh quote derived from the amount and currency.

Response

Successful Response

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.

payment_id

string

required

Halliday's payment id. Use it to poll status.

deposit_address

string

required

The one-time-wallet (OTW) deposit address for this payment, owned solely by the user's wallet (non-custodial).

checkout_url

string

required

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

string

required

Short, agent-actionable guidance: open the checkout link, pay, then poll status until delivered.

status

enum<string>

required

Initial lifecycle state (typically pending).

Available options:

pending,

processing,

delivered,

failed

quote

OnrampQuote · object

required

The resolved quote this payment was created against.

Show child attributes

Get a fiat on-ramp quote (card -> USDC on Ethereum)Get the status of a fiat on-ramp payment

⌘I