Placing dShare Orders with Alchemy

This page details how orders can be placed using the Alchemy Account kit & Dinari SDK

Ordering with Alchemy Account Kit Smart Wallet

This guide shows how to place a dShare order using the Dinari Partner SDK (@dinari/api-sdk) where an Alchemy Account Kit smart contract wallet signs the order intent.

How it works

When the funder is an Account Kit smart wallet, you must use the externally-signed path. The flow is:

  1. Create an order request and get back the EIP-712 permit to sign.
  2. Sign the permit with the smart wallet (produces an ERC-1271 contract-account signature).
  3. Submit the signed permit — Dinari-sponsored or self-sponsored.
  4. Poll the order request until it reaches a terminal state.
🚧

NOTE: Smart-wallet signatures are not EOA signatures

A standard ERC-2612 permit() recovers the signer with ecrecover, which only accepts EOA signatures and will reject a smart-contract wallet. A contract-wallet (ERC-1271) signature is only honored if the verifying contract supports ERC-1271 as Uniswap Permit2 does. Confirm your payment path validates ERC-1271/Permit2 (not raw ERC-2612) before going to mainnet.

Prerequisites

To place an order, an Entity needs:

  • A valid KYC on the Entity.
  • A valid Account under the Entity.
  • Enough payment-token balance in the smart wallet to cover the order plus fees.

For this integration you also need:

  • Create a Dinari partner account and generate an API Key ID and API Secret Key in partners.dinari.com. Start in sandbox.
  • Create an Alchemy API key in dashboard.alchemy.com, and optionally create a Gas Manager policy ID for gas sponsorship.
  • Store the smart wallet's owner private key in a server-side secret store. This is the signer/owner of the account — not the account address.
  • Load secrets from your secret manager at runtime, but do not paste secret values into examples, logs, or client-side code.

Step 1: Initialize the Dinari client

import { DinariClient, DinariEnvironment } from "@dinari/api-sdk";

const dinariCredentials = await loadDinariCredentialsFromSecretManager();

const dinari = new DinariClient({
  apiKeyId: dinariCredentials.apiKeyID,
  apiSecretKey: dinariCredentials.apiSecretKey,
  environment: DinariEnvironment.Sandbox, // defaults to DinariEnvironment.Production
});
import os

from dinari_api_sdk import DinariClient
from dinari_api_sdk.environment import DinariClientEnvironment

client = DinariClient(
    api_key_id=os.environ["DINARI_API_KEY_ID"],
    api_secret_key=os.environ["DINARI_API_SECRET_KEY"],
    environment=DinariClientEnvironment.SANDBOX,  # defaults to DinariClientEnvironment.PRODUCTION
)
package main

import (
	"context"
	"os"

	dinari "github.com/dinaricrypto/dinari-api-sdk-go"
	client "github.com/dinaricrypto/dinari-api-sdk-go/client"
	option "github.com/dinaricrypto/dinari-api-sdk-go/option"
)

var (
	c = client.NewDinariClient(
		option.WithBaseURL(dinari.Environments.Sandbox), // Defaults to production when omitted
		option.WithAPIKeyID(os.Getenv("DINARI_API_KEY_ID")),
		option.WithAPISecretKey(os.Getenv("DINARI_API_SECRET_KEY")),
	)
	ctx = context.Background()
)
import com.dinari.api.DinariClient;
import com.dinari.api.core.Environment;

public class Main {
    static final DinariClient client = DinariClient.builder()
            .environment(Environment.SANDBOX) // defaults to Environment.PRODUCTION
            .apiKeyId(System.getenv("DINARI_API_KEY_ID"))
            .apiSecretKey(System.getenv("DINARI_API_SECRET_KEY"))
            .build();
}

The smart wallet interactions in this guide use Alchemy Account Kit (TypeScript). The Python, Go and Java tabs show the Dinari API calls that stand on their own (client setup, stock lookup, permit creation, Dinari-sponsored submission and order status), with the same variable names.

Step 2: Create the headless smart wallet client

This is the server-side signer client (not the React hooks path). The smart account is a Modular Account V2 whose owner is a LocalAccountSigner built from a private key.

import { createModularAccountV2Client } from "@account-kit/smart-contracts";
import { LocalAccountSigner } from "@aa-sdk/core";
import { alchemy, arbitrumSepolia } from "@account-kit/infra";

const walletSecrets = await loadWalletSecretsFromSecretManager();
const alchemyConfig = await loadAlchemyConfigFromSecretManager();

const owner = LocalAccountSigner.privateKeyToAccountSigner(
  walletSecrets.ownerPrivateKey as `0x${string}`,
);

const smartAccountClient = await createModularAccountV2Client({
  mode: "default",
  chain: arbitrumSepolia,
  transport: alchemy({ apiKey: alchemyConfig.apiKey }),
  signer: owner,
});

// The smart contract account address (not the owner EOA):
const smartWalletAddress = smartAccountClient.account.address;

signTypedData on this client produces a signature validatable via ERC-1271. If the account is not yet deployed, the signature is wrapped per ERC-6492.

Step 3: Deploy the smart account

A Modular Account V2 deploys on its first user operation. On-chain ERC-1271 validation requires the account to be deployed (unless the verifier supports ERC-6492), so deploy it before signing permits.

const isDeployed = await smartAccountClient.account.isAccountDeployed();

if (!isDeployed) {
  const deployOp = await smartAccountClient.sendUserOperation({
    uo: { target: smartAccountClient.account.address, data: "0x", value: 0n },
  });
  await smartAccountClient.waitForUserOperationTransaction({ hash: deployOp.hash });
}
🚧

Deployment needs gas

The deploy user operation costs gas. Fund the account with native gas or attach an Alchemy Gas Manager policy to the client.

Step 4: Complete KYC and link your wallet (one-time)

These steps run once per user. KYC requires the user to complete a hosted flow, so it cannot be fully automated server-side.

// Entity + KYC
const entity = await dinari.entities.createEntities({ name: "Jane Doe" });
const kyc = await dinari.kyc.createManagedEntityKycEmbed({ entityId: entity.id });
console.log("Send the user to:", kyc.embedUrl);

// Account
const account = await dinari.accounts.createEntityAccounts({ entityId: entity.id });
const accountId = account.id;

// Link the smart wallet (signed with the wallet, ERC-1271)
const nonceResp = await dinari.wallets.getAccountWalletConnectionNonce({
  accountId,
  walletAddress: smartWalletAddress,
  chainId: "eip155:421614",
});

const linkSignature = await smartAccountClient.signMessage({
  message: nonceResp.message,
});

await dinari.wallets.createAccountWalletConnection({
  accountId,
  chainId: "eip155:421614",
  nonce: nonceResp.nonce,
  signature: linkSignature,
  walletAddress: smartWalletAddress,
});
📘

Linking also uses an ERC-1271 signature

The wallet-linking nonce is signed by the smart wallet, so the account must be deployed (Step 3) for the signature to validate.

Step 5: Select the stock and order parameters

const stocks = await dinari.marketData.getStocks({ symbols: "AAPL", limit: 20 });
const stock = (Array.isArray(stocks) ? stocks : stocks.data).find((s) => s.symbol === "AAPL");
if (!stock) throw new Error("Stock not found");
const stockId = stock.id;
stocks = client.market_data.get_stocks(symbols="AAPL", limit=20)
stock = next((s for s in (stocks if isinstance(stocks, list) else stocks.data) if s.symbol == "AAPL"), None)
if stock is None:
    raise RuntimeError("Stock not found")
stock_id = stock.id
stocks, err := c.MarketData.GetStocks(ctx, &dinari.GetStocksRequest{
	Symbols: []*string{dinari.String("AAPL")},
	Limit:   dinari.Int(20),
})
if err != nil {
	log.Fatalf("Failed to list stocks: %v", err)
}

var stockID string
for _, s := range stocks.GetPaginatedStockResponse().Data {
	if s.Symbol == "AAPL" {
		stockID = s.ID
	}
}
if stockID == "" {
	log.Fatal("Stock not found")
}
var stocks = client.marketData().getStocks(
        GetStocksRequest.builder().symbols("AAPL").limit(20).build());
String stockId = ((PaginatedStockResponse) stocks.get()).getData().stream()
        .filter(s -> s.getSymbol().equals("AAPL"))
        .findFirst()
        .orElseThrow(() -> new RuntimeException("Stock not found"))
        .getId();
FieldMeaning
stock_idDinari UUID of the dShare (from marketData.getStocks()).
order_side"BUY" or "SELL".
order_type"MARKET" or "LIMIT".
order_tifTime-in-force, e.g. "DAY".
payment_tokenPayment-token ERC-20 address (e.g. USDC on the target chain).
payment_token_quantityFor a market buy, the notional amount of payment token to spend.
chain_idCAIP-2 chain id, e.g. "eip155:421614".
📘

Amount fields by order type

Market buys use payment_token_quantity (notional). Market sells and limit orders use asset_quantity (number of dShares); limit orders also take limit_price. Fees are added on top of the notional.

Step 6: Create the order permit

const orderConfig = await loadOrderConfig();

const permitResponse = await dinari.orderRequests.createEip155OrderRequestPermit({
  accountId,
  chainId: "eip155:421614",
  orderSide: "BUY",
  orderType: "MARKET",
  orderTif: "DAY",
  stockId,
  paymentToken: orderConfig.paymentTokenAddress,
  paymentTokenQuantity: 10.0, // notional to spend
});

const orderRequestId = permitResponse.orderRequestId;
const permit = permitResponse.permit; // { domain, types, primaryType, message }
permit_response = client.order_requests.create_eip155order_request_permit(
    account_id=account_id,
    chain_id="eip155:421614",
    order_side="BUY",
    order_type="MARKET",
    order_tif="DAY",
    stock_id=stock_id,
    payment_token=payment_token_address,
    payment_token_quantity=10.0,  # notional to spend
)

order_request_id = permit_response.order_request_id
permit = permit_response.permit  # { domain, types, primaryType, message }
permitResponse, err := c.OrderRequests.CreateEip155OrderRequestPermit(ctx, &dinari.Eip155OrderRequestPermitInput{
	AccountID:            accountID,
	ChainID:              dinari.ChainIDEip155421614,
	OrderSide:            dinari.OrderSideBuy,
	OrderType:            dinari.OrderTypeMarket,
	OrderTif:             dinari.OrderTifDay,
	StockID:              dinari.String(stockID),
	PaymentToken:         paymentTokenAddress,
	PaymentTokenQuantity: dinari.Float64(10.0), // notional to spend
})
if err != nil {
	log.Fatalf("Failed to create permit: %v", err)
}

orderRequestID := permitResponse.OrderRequestID
permit := permitResponse.Permit // { domain, types, primaryType, message }
var permitResponse = client.orderRequests().createEip155OrderRequestPermit(
        accountId,
        Eip155OrderRequestPermitInput.builder()
                .chainId(ChainId.EIP155421614)
                .orderTif(OrderTif.DAY)
                .orderSide(OrderSide.BUY)
                .orderType(OrderType.MARKET)
                .paymentToken(paymentTokenAddress)
                .stockId(stockId)
                .paymentTokenQuantity(10.0) // notional to spend
                .build());

String orderRequestId = permitResponse.getOrderRequestId();
Map<String, Object> permit = permitResponse.getPermit(); // { domain, types, primaryType, message }

The response carries an order_request_id and a permit object shaped exactly like an EIP-712 TypedDataDefinition.

Step 7: Sign the permit with the smart wallet

const permitSignature = await smartAccountClient.signTypedData({
  typedData: {
    domain: permit.domain,
    types: permit.types,
    primaryType: permit.primaryType,
    message: permit.message,
  },
});

Step 8: Submit the signed order

Choose one of two submission modes.

Dinari-sponsored — Dinari pays gas and submits on-chain:

const result = await dinari.orderRequests.createEip155OrderRequestPermitTransaction({
  accountId,
  body: { orderRequestId, permitSignature },
});
permit_signature = "your-permit-signature"  # The signature from Step 7

result = client.order_requests.create_eip155order_request_permit_transaction(
    account_id=account_id,
    order_request_id=order_request_id,
    permit_signature=permit_signature,
)
permitSignature := "your-permit-signature" // The signature from Step 7

result, err := c.OrderRequests.CreateEip155OrderRequestPermitTransaction(ctx, &dinari.CreateEip155OrderRequestPermitTransactionRequest{
	AccountID: accountID,
	Body: &dinari.Eip155OrderRequestPermitTransaction{
		OrderRequestID:  orderRequestID,
		PermitSignature: permitSignature,
	},
})
if err != nil {
	log.Fatalf("Failed to submit order request: %v", err)
}
fmt.Printf("%+v\n", result)
String permitSignature = "your-permit-signature"; // The signature from Step 7

var result = client.orderRequests().createEip155OrderRequestPermitTransaction(
        accountId,
        CreateEip155OrderRequestPermitTransactionRequest.builder()
                .body(Eip155OrderRequestPermitTransaction.builder()
                        .orderRequestId(orderRequestId)
                        .permitSignature(permitSignature)
                        .build())
                .build());
System.out.println(result);

Self-sponsored — you send the transaction from the smart wallet:

const tx = await dinari.orderRequests.createEip155PermitTransaction({
  accountId,
  body: { orderRequestId, permitSignature },
});

const op = await smartAccountClient.sendUserOperation({
  uo: {
    target: tx.contractAddress as `0x${string}`,
    data: tx.data as `0x${string}`,
    value: BigInt(tx.value ?? 0),
  },
});

const txHash = await smartAccountClient.waitForUserOperationTransaction({
  hash: op.hash,
});

Step 9: Poll order status

const orderRequest = await dinari.orderRequests.getOrderRequestById({
  accountId,
  orderRequestId,
});
console.log("Status:", orderRequest.status);
order_request = client.order_requests.get_order_request_by_id(
    account_id=account_id,
    order_request_id=order_request_id,
)
print("Status:", order_request.status)
orderRequest, err := c.OrderRequests.GetOrderRequestByID(ctx, &dinari.GetOrderRequestByIDRequest{
	AccountID:      accountID,
	OrderRequestID: orderRequestID,
})
if err != nil {
	log.Fatalf("Failed to get order request: %v", err)
}
fmt.Println("Status:", orderRequest.Status)
var orderRequest = client.orderRequests().getOrderRequestById(accountId, orderRequestId);
System.out.println("Status: " + orderRequest.getStatus());

Two status concepts exist:

  • OrderRequestStatus — the request status (pre-brokerage), on the OrderRequest.
  • BrokerageOrderStatus — the resulting on-chain/brokerage Order, via dinari.orders.getOrderById({ accountId, orderId }).

Poll the order request to a terminal state, then track the resulting order and fulfillments.

Common errors

SymptomLikely causeFix
Permit signature rejected on submitPayment path uses raw ERC-2612 (ecrecover), which rejects contract-wallet signaturesConfirm Dinari's verifier supports ERC-1271 / Permit2 for your token and chain
isValidSignature revertsSmart account not deployedDeploy the account first (Step 3)
Wallet-linking failsAccount not deployed when linking signature was producedDeploy, then link
Insufficient fundsPayment-token balance below notional + feesFund the smart wallet; budget for fees on top of the notional
User operation fails in self-sponsored modeNo native gas and no paymasterFund the wallet or attach a Gas Manager policy

Did this page help you?