Conversions

Conversions capture atomic two-asset swaps — moving a balance from one asset to another at a venue, with distinct source and destination amounts. Stablecoin redemption (USDC ↔ USD), wrapped-asset swaps, and any other direct asset-to-asset exchange that bypasses the order book belong here, separate from both Payments and Orders.

The Conversion model#

A Conversion is a single record with a stable identity (reference from the upstream venue), source and destination assets, source and destination amounts at each side's precision, fees, a status (PENDING / COMPLETED / FAILED), and source/destination account references on the venue.

The defining characteristic versus a Payment: a Conversion swaps two distinct assets atomically, with two distinct amounts. A Payment moves a single asset on a single leg.

The defining characteristic versus an Order: a Conversion bypasses the order book — there's no price discovery, no time-in-force, no partial-fill lifecycle. It either completes at the venue's quoted rate or fails.

1:1 conversions#

Some conversions are nominally equal across both legs and only differ by precision — stablecoin redemption is the canonical case: 10,000 USDC ↔ 10,000 USD where the integer amounts are 10000000000 (USDC at /6) and 1000000 (USD at /2). The two-asset / two-amount shape still applies; the venue just guarantees parity. Venues that expose a single amount field on the conversion row (like Coinbase Prime) trigger this code path — the connector populates both sourceAmount and destinationAmount from that single value, parsed at each side's precision. True FX conversions populate the two amounts independently from distinct upstream fields.

Listing and inspecting Conversions#

curl -s "$STACK/api/payments/v3/conversions?pageSize=15" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -s "$STACK/api/payments/v3/conversions/$CONVERSION_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

Filter by posting a query body — for example, all completed conversions on a connector:

curl -s "$STACK/api/payments/v3/conversions?pageSize=15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "$and": [
      { "$match": { "connectorID": "'$CONNECTOR_ID'" } },
      { "$match": { "status": "COMPLETED" } }
    ]
  }' | jq

fctl does not ship conversions subcommands; use the API directly.

Capability#

A connector emits Conversions by implementing the FETCH_CONVERSIONS capability. See the connector capabilities matrix for which connectors expose this.

Implementations#

• Coinbase Prime — covers stablecoin redemption and other 1:1 swaps via the Coinbase Prime transactions feed filtered to type CONVERSION.