Documentation

Everything you need to move a shipment

From your first escrow to integrating the API — StellarExpress is designed to be self-hostable and fully documented.

Guides

Getting started

Create your first shipment
Fund an escrow and list it for carriers in under five minutes.
Connect a wallet
Freighter, hardware wallets, and passkey signers.
Understanding parties
Sender, Carrier, Receiver, Arbiter.

Shipment lifecycle

Open → Accepted → In transit → Delivered
The four states every shipment moves through.
Milestone splits
Setting pickup_release_bps per shipment.
Cancellation & reclaim
Refund paths before and after a carrier accepts.

Disputes

Raising a dispute
Who can raise one, and when.
Arbiter resolution
Bounded authority — only unreleased funds are ever split.

API reference

GraphQL schema
Queries and mutations for shipments, tracking, disputes, reviews.
Stellar integration
Non-custodial XDR build & submit flow.
Webhooks
Subscribe to shipment and dispute events.

Quickstart

Create a shipment with GraphQL

The API is code-first GraphQL. Every mutation returns exactly the fields your UI needs.

mutation CreateShipment {
  createShipment(input: {
    receiverName: "Chidi Okoro"
    receiverAddress: "GABC...RECEIVER"
    originLabel: "Lagos"
    destinationLabel: "Abuja"
    category: FOOD
    assetCode: USDC
    totalAmount: 5000
    pickupReleaseBps: 4000
    deliveryDeadlineAt: "2026-09-01T00:00:00Z"
  }) {
    id
    status
  }
}

Non-custodial by design

The build → sign → submit flow

Every on-chain action follows the same three steps — the backend never touches a secret key.

// 1. Ask the API to build unsigned XDR
const { xdr } = await api.post('/stellar/build', {
  sourcePublicKey: wallet.publicKey,
  method: 'confirm_pickup',
  args: [shipmentId],
});

// 2. Sign client-side — StellarExpress never sees your key
const signedXdr = await freighter.signTransaction(xdr);

// 3. Submit the signed envelope
await api.post('/stellar/submit', { signedXdr });

Full API reference and contract source live in the developer hub.

Ready to build?

Clone the repos, spin up Postgres with Docker, and you have a working StellarExpress stack in minutes.

View the repos on GitHub