Equities Quickstart

Set Up

import "dotenv/config";

import { unpackMint } from "@solana/spl-token";
import { Connection, Keypair, PublicKey, VersionedTransaction } from "@solana/web3.js";
import bs58 from "bs58";

const DFLOW_TRADE_API_URL = process.env.DFLOW_TRADE_API_URL ?? "https://dev-quote-api.dflow.net";
const DFLOW_EQUITIES_SUBMIT_URL =
  process.env.DFLOW_EQUITIES_SUBMIT_URL ?? "https://TODO-equities-host.dflow.net/submit-transaction";
const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // the key must be enabled for equities
const SOLANA_RPC_URL = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";

const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
const TICKER = "AAPL";
const AMOUNT = 1_000_000; // 1 USDC (6 decimals)

const connection = new Connection(SOLANA_RPC_URL, "confirmed");
const keypair = Keypair.fromSecretKey(
  bs58.decode(process.env.SOLANA_PRIVATE_KEY ?? "")
);

const headers: Record<string, string> = {};
if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

Find the Equity Mint

Find Equities adds retries and lookup by mint.

const equitiesResponse = await fetch(`${DFLOW_TRADE_API_URL}/equities`, { headers });
if (!equitiesResponse.ok) {
  throw new Error(`GET /equities failed: ${equitiesResponse.status} ${await equitiesResponse.text()}`);
}

const equities: { ticker: string; mint: string; provider: string }[] = await equitiesResponse.json();
const equity = equities.find((e) => e.ticker === TICKER);
if (!equity) {
  throw new Error(`${TICKER} is not in the supported equities`);
}

Call the Order Endpoint

Set inputMint to USDC and outputMint to the equity mint. Pass userPublicKey so the /order response includes a transaction. Equity Fills describes the equity fields in the response.

const params = new URLSearchParams({
  inputMint: USDC_MINT,
  outputMint: equity.mint,
  amount: AMOUNT.toString(),
  userPublicKey: keypair.publicKey.toBase58(),
});

const buyResponse = await fetch(`${DFLOW_TRADE_API_URL}/order?${params}`, { headers });
const buy = await buyResponse.json();
if (!buyResponse.ok || !buy.transaction) {
  throw new Error(`GET /order failed: ${JSON.stringify(buy)}`);
}

console.log("executionMode:", buy.executionMode, "submitEndpointRequired:", buy.submitEndpointRequired ?? false);
console.log("  outAmount:", buy.outAmount);
console.log("  outAmountScaledUi:", buy.outAmountScaledUi ?? "<mint has no ScaledUiAmount extension>");

Sign and Choose the Submission Path

The user signs the transaction. submitEndpointRequired and executionMode decide the submission path: Submit a Direct Fill for a response with submitEndpointRequired: true, and Submit an Escrow Fill for an async response. Any other response is an ordinary route, and the app sends it through its own RPC.

const transaction = VersionedTransaction.deserialize(Buffer.from(buy.transaction, "base64"));
transaction.sign([keypair]);

if (buy.submitEndpointRequired) {
  await submitDirectFill(transaction, buy.lastValidBlockHeight);
} else if (buy.executionMode === "async") {
  await submitEscrowFill(transaction);
} else {
  console.log(await connection.sendRawTransaction(transaction.serialize()));
}

Submit a Direct Fill

The app sends the signed transaction to the submit transaction endpoint and confirms the signature onchain through its own RPC. Submitting Equity Transactions lists the endpoint’s errors.

async function submitDirectFill(transaction: VersionedTransaction, lastValidBlockHeight: number) {
  const submitter = new Connection(DFLOW_EQUITIES_SUBMIT_URL, { httpHeaders: headers });
  const signature = await submitter.sendRawTransaction(transaction.serialize());
  console.log(`  Tx: https://orbmarkets.io/tx/${signature}`);

  const { value } = await connection.confirmTransaction({
    signature,
    blockhash: transaction.message.recentBlockhash,
    lastValidBlockHeight,
  });
  console.log(value.err ? `Failed: ${JSON.stringify(value.err)}` : "Filled");
}

Submit an Escrow Fill

The transaction of an async response is complete after the user signs, so the app sends it through its own RPC. The app then tracks the escrow fill with this signature and the response’s lastValidBlockHeight, as in Track an Escrow Fill.

async function submitEscrowFill(transaction: VersionedTransaction) {
  const signature = await connection.sendRawTransaction(transaction.serialize());
  console.log(`  Tx: https://orbmarkets.io/tx/${signature}`);
}

Sell an Equity

A sell sets the equity mint as inputMint. amount is the raw token amount in the equity mint’s decimals, before the ScaledUiAmount multiplier. The app reads the decimals from the mint account, decoding it with the token program that owns the account.

const mintAddress = new PublicKey(equity.mint);
const mintAccount = await connection.getAccountInfo(mintAddress);
if (!mintAccount) {
  throw new Error(`Mint account ${equity.mint} not found`);
}
const { decimals } = unpackMint(mintAddress, mintAccount, mintAccount.owner);

const sellParams = new URLSearchParams({
  inputMint: equity.mint,
  outputMint: USDC_MINT,
  amount: Math.round(0.5 * 10 ** decimals).toString(),
  userPublicKey: keypair.publicKey.toBase58(),
});

const sellResponse = await fetch(`${DFLOW_TRADE_API_URL}/order?${sellParams}`, { headers });
const sell = await sellResponse.json();
if (!sellResponse.ok || !sell.transaction) {
  throw new Error(`GET /order failed: ${JSON.stringify(sell)}`);
}

console.log("executionMode:", sell.executionMode, "submitEndpointRequired:", sell.submitEndpointRequired ?? false);
console.log("  inAmountScaledUi:", sell.inAmountScaledUi ?? "<mint has no ScaledUiAmount extension>");
console.log("  outAmount (USDC):", sell.outAmount);

The user signs sell.transaction, and the app then branches as above.

Equities

Recipes

Concepts

Equities Quickstart

Submit a Direct Fill

Submit an Escrow Fill

Sell an Equity

​Submit a Direct Fill

​Submit an Escrow Fill

​Sell an Equity

Submit a Direct Fill

Submit an Escrow Fill

Sell an Equity