Convert with a Quote#

Use this when an agent needs to convert between supported assets.

Prerequisites#

The source and destination assets are allowed.
The agent has conversion authority.
The account has enough source balance.

Create a Quote#

Agent API amount fields are decimal asset-unit strings. Here, "amount": "1" means 1 USDC. slippage_percent is a number.

curlrequest

curl -sS https://api.hightop.com/v1/agent/conversions/quote \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "Idempotency-Key: quote-$(uuidgen)" \
  -d '{
    "from_asset": "USDC",
    "to_asset": "ETH",
    "amount": "1",
    "slippage_percent": 1
  }'

Quotes expire after 60 seconds and are single-use.

Execute the Quote#

curlrequest

export QUOTE_ID="00000000-0000-0000-0000-000000000000"
 
curl -sS https://api.hightop.com/v1/agent/conversions \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "Idempotency-Key: conversion-$(uuidgen)" \
  -d "{
    \"quote_id\": \"$QUOTE_ID\"
  }"

Optional TypeScript SDK Shape#

typescriptexample

const quote = await client.v1.agent.conversions.quote(
  {
    from_asset: 'USDC',
    to_asset: 'ETH',
    amount: '1',
    slippage_percent: 1,
  },
  { idempotencyKey: `quote-${crypto.randomUUID()}` },
)
 
const conversion = await client.v1.agent.postConversions(
  { quote_id: quote.quote.quote_id },
  { idempotencyKey: `conversion-${crypto.randomUUID()}` },
)

Follow Up#

Poll the returned operation or subscribe to conversion.executed and conversion.execution_failed.

Likely errors: quote_expired, quote_already_consumed, slippage_exceeded, price_stale, asset_not_allowed, protocol_not_allowed, insufficient_funds.