Stablecoin Conversion

The Conversion API allows you to price, confirm, and monitor asset conversions within a portfolio. The typical flow involves:

Create Quote → Price the conversion request.
Show rate, fee, and valid_until to the customer.
Create Hedge → Confirm the conversion using the quote_id.
Retrieve Hedge → Monitor hedge execution status, fills, and timestamps.

Create Quote

Endpoint

POST /v1/portfolios/portfolio_id/conversions/quote

Purpose

Generate a short-lived quote for converting between two assets. Use this to display pricing and fees to your customer before execution.

Request Parameters

Field	Type	Required	Description
from_asset	object	Yes/No	Source asset details. Must include asset, network, and optionally amount (if not providing to_asset.amount).
to_asset	object	Yes/No	Target asset details. Must include asset, network, and optionally amount (if not providing from_asset.amount).

Example Request

{
  "from_asset": {
    "asset": "USD",
    "network": "US_ACH",
    "amount": "1000.00"
  },
  "to_asset": {
    "asset": "USDC",
    "network": "ETH"
  }
}

Example Response

{
  "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3",
  "rate": "1.0000",
  "fee": "5.00",
  "fee_asset": "USD",
  "from_asset": {
    "asset": "USD",
    "network": "US_ACH",
    "amount": "1000.00"
  },
  "to_asset": {
    "asset": "USDC",
    "network": "ETH",
    "amount": "995.00"
  },
  "valid_until": "2025-08-21T07:56:57.981Z",
  "created_at": "2025-08-21T07:56:57.981Z",
  "modified_at": "2025-08-21T07:56:57.981Z"
}

Create Hedge

Endpoint

POST /v1/portfolios/portfolio_id/conversions/hedge

Purpose

Confirm the quote and lock the conversion into a hedge. This step reserves funds and ensures execution.

Request Parameters

Field	Type	Required	Description
quote_id	string	Yes	Identifier from Create Quote that you wish to hedge.

Example Request

{
  "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3"
}

Example Response

{
  "hedge_id": "hedge-uuid",
  "conversion_id": "conv-uuid",
  "status": "pending",
  "executed_at": null,
  "created_at": "2025-08-21T08:00:01.000Z"
}

Retrieve Hedge

Endpoint

GET /v1/portfolios/portfolio_id/conversions/hedge

Purpose

Retrieve hedge details for a specific conversion, including execution status and timestamps.

Response Fields

Field	Type	Description
hedge_id	string	Unique identifier for the hedge.
conversion_id	string	Associated conversion transaction.
status	string	Current state of the hedge (e.g., pending, executed, failed).
executed_at	datetime	Timestamp when the hedge was executed (if applicable).
created_at	datetime	Timestamp when the hedge was created.
updated_at	datetime	Last update timestamp for the hedge record.
fills	array	List of partial or full execution details (if hedge is filled).

Example Response

{
  "hedge_id": "hedge-uuid",
  "conversion_id": "conv-uuid",
  "status": "executed",
  "executed_at": "2025-08-21T08:05:10.000Z",
  "created_at": "2025-08-21T08:00:01.000Z",
  "updated_at": "2025-08-21T08:05:10.000Z",
  "fills": [
    {
      "fill_id": "fill-uuid-1",
      "amount": "500.00",
      "asset": "USDC",
      "network": "ETH",
      "executed_at": "2025-08-21T08:03:00.000Z"
    },
    {
      "fill_id": "fill-uuid-2",
      "amount": "495.00",
      "asset": "USDC",
      "network": "ETH",
      "executed_at": "2025-08-21T08:05:10.000Z"
    }
  ]
}