Quick Start

• A YieldFabric account in a running deployment (your own dev environment, or a hosted one).
• curl and jq for the inline snippets (or substitute your language of choice — every step is plain HTTP).
• The base URLs your app may talk to. Defaults shown below — substitute your own if you're running a self-hosted deployment.

export YF_AUTH=https://auth.yieldfabric.com       # sign-in + JWT issuance
export YF_GATEWAY=https://api.yieldfabric.com     # federated GraphQL
export YF_PAYMENTS=https://pay.yieldfabric.com    # REST message polling
export YF_AGENTS=https://agents.yieldfabric.com   # working groups, threads, streams

Both paths return the same access JWT — 15-min lifetime, 30-day single-use refresh. Use email + password for human users; use an API key for any server-side caller (operators, app backends, batch jobs). API keys are revocable per-key and auditable, and they keep plaintext passwords out of env vars.

# Browser / human-driven: email + password
LOGIN=$(curl -s -X POST $YF_AUTH/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "your-password"
    }')

export TOKEN=$(echo "$LOGIN" | jq -r .token)
export REFRESH=$(echo "$LOGIN" | jq -r .refresh_token)
export USER_ID=$(echo "$LOGIN" | jq -r .user.id)

# Backend service: exchange a long-lived API key for a short-lived JWT
# (issue the key once with POST /auth/api-key/generate; store as $API_KEY)
# LOGIN=$(curl -s -X POST $YF_AUTH/auth/api-key \
#   -H "Content-Type: application/json" \
#   -d "{\"api_key\":\"$API_KEY\"}")
# export TOKEN=$(echo "$LOGIN" | jq -r .token)

↳ Same JWT works against every service. Tokens last 15 min; refresh via POST $YF_AUTH/auth/refresh with the refresh_token (single-use — store the new one immediately).

/protected/jwt decodes the bearer and returns the caller's claims — user id, account address, default wallet id. You'll thread the wallet id into nearly every mutation below (it's the canonical way to refer to yourself or a counterparty without leaking entity-name resolution into your client).

PROFILE=$(curl -s $YF_AUTH/protected/jwt \
    -H "Authorization: Bearer $TOKEN")

export USER_ID=$(echo "$PROFILE" | jq -r .user_id)
export WALLET_ID=$(echo "$PROFILE" | jq -r .default_wallet_id)
echo "User: $USER_ID · Wallet: $WALLET_ID"

↳ GET $YF_AUTH/auth/users/me returns the same caller from the user-table side (with role, email, is_external_signer). Either works — use /protected/jwt when you only need the claims, /users/me when you also want the role/profile metadata.

The federated gateway at api.yieldfabric.com/graphql is the read endpoint your app talks to for cross-subgraph queries. Same JWT, joined views: entity lookups, the wallet activity feed, and payment/contract listings.

# Recent activity on your wallet — merged payments + messages, newest first
curl -s -X POST $YF_GATEWAY/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "query($w: String!) { walletFlow { activity(walletId: $w, limit: 25) { nextCursor items { __typename ... on PaymentActivity { timestamp payment { id status amount assetId } } ... on MessageActivity { timestamp message { id messageType status executed } } } } } }",
      "variables": { "w": "'$WALLET_ID'" }
    }' | jq

↳ cursor is opaque — pass nextCursor from the previous page back in as cursor for the next page. nextCursor: null means exhausted. Same (walletId, limit, cursor) triple returns the same page on any replica.

The instant mutation enqueues a confidential on-chain transfer. The mutation returns as soon as the GraphQL gateway accepts the message — actual settlement is async. Pass destinationWalletId when you have the recipient's wallet UUID (canonical) or destinationId if you only have an entity name / email.

# Substitute with your recipient's wallet id. Use /protected/jwt off
# their bearer (or look up the entity) to get a real UUID.
export RECIPIENT_WALLET=00000000-0000-0000-0000-000000000000

SEND=$(curl -s -X POST $YF_GATEWAY/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "mutation($input: InstantSendInput!) { instant(input: $input) { success messageId paymentId } }",
      "variables": {
        "input": {
          "destinationWalletId": "'$RECIPIENT_WALLET'",
          "assetId": "aud-token-asset",
          "amount": "10",
          "idempotencyKey": "'"$(uuidgen)"'"
        }
      }
    }')

export MESSAGE_ID=$(echo "$SEND" | jq -r .data.instant.messageId)
echo "Enqueued: $MESSAGE_ID"

↳ Amount is an integer string (no decimals). idempotencyKey must be a fresh UUIDv4 per call — never a deterministic hash like sha256(user+action); the resolver dedupes on it and a retry after a stuck message just returns the stuck messageId again. Omitting the key is also fine (the resolver auto-generates one).

On-chain execution is asynchronous. The canonical pattern for backend callers (Python SDK, shell scripts, operator) is REST polling at 2-second intervals against /api/users/{user_id}/messages/{message_id} — simpler than SSE, no missed-event race. Terminal when executed is non-null.

until curl -s -H "Authorization: Bearer $TOKEN" \
    "$YF_PAYMENTS/api/users/$USER_ID/messages/$MESSAGE_ID" \
    | jq -e '.executed' > /dev/null; do
  echo "Waiting…"
  sleep 2
done

curl -s -H "Authorization: Bearer $TOKEN" \
    "$YF_PAYMENTS/api/users/$USER_ID/messages/$MESSAGE_ID" | jq

↳ Status progression: Pending → Validating → Executing → Completed (or Failed / ManualSignature). The "executed" field flips when the on-chain receipt lands. Cap your polling at ~300s and surface failures from the response envelope.