API Reference

The ƒxyz Network API is a GraphQL API that provides access to all network functionality.

Endpoint

Production: https://api.fxyz.network/graphql
Development: http://localhost:3002/graphql

Authentication

JWT Tokens

All API requests require a valid JWT token from Privy:

const headers = {
  'Authorization': `Bearer ${privyAccessToken}`,
  'Content-Type': 'application/json',
};

Getting a Token

import { usePrivy } from '@privy-io/react-auth';

function MyComponent() {
  const { getAccessToken } = usePrivy();
  
  const token = await getAccessToken();
  // Use token in API requests
}

Core Mutations

Bootstrap User

Creates initial persona and member record:

mutation BootstrapUser {
  bootstrapUser {
    member {
      id
      wallets {
        address
        chain
      }
    }
    persona {
      id
      did
      name
      isPublic
    }
  }
}

Issue Membership

Mints membership NFT (admin only):

mutation IssueMembership($userId: ID!) {
  issueMembership(userId: $userId) {
    id
    membershipNFTMint
    status
    member {
      id
      wallets {
        address
      }
    }
  }
}

Mint My Membership

Self-mint membership NFT:

mutation MintMyMembership {
  mintMyMembership {
    membershipNFTMint
    transactionSignature
    member {
      id
      membershipNFTMint
    }
  }
}

Generate Membership Proof

Create privacy-aware membership proof:

mutation GenerateMembershipProof($memberId: ID!) {
  generateMembershipProof(memberId: $memberId) {
    id
    membershipNFTMint
    totalPersonas
    personas_public {
      id
      name
      did
    }
    personas_private_count
    generatedAt
  }
}

Core Queries

Get Current User

query GetCurrentUser {
  getCurrentUser {
    id
    wallets {
      address
      chain
      isPrimary
    }
    personas {
      id
      name
      did
      isPublic
      isDefault
    }
    membershipNFTMint
    membershipProof {
      id
      totalPersonas
      personas_public {
        id
        name
      }
      personas_private_count
    }
  }
}

Get Member by ID

query GetMember($id: ID!) {
  getMember(id: $id) {
    id
    wallets {
      address
      chain
    }
    personas {
      id
      name
      isPublic
    }
    membershipNFTMint
  }
}

Get Persona

query GetPersona($id: ID!) {
  getPersona(id: $id) {
    id
    name
    did
    isPublic
    isDefault
    member {
      id
      membershipNFTMint
    }
  }
}

Persona Management

Create Persona

mutation CreatePersona($name: String!, $isPublic: Boolean) {
  createPersona(name: $name, isPublic: $isPublic) {
    id
    name
    did
    isPublic
    member {
      id
    }
  }
}

Update Persona

mutation UpdatePersona($id: ID!, $name: String, $isPublic: Boolean) {
  updatePersona(id: $id, name: $name, isPublic: $isPublic) {
    id
    name
    isPublic
  }
}

Set Active Persona

mutation SetActivePersona($personaId: ID!) {
  setActivePersona(personaId: $personaId) {
    id
    name
    did
  }
}

Knowledge Graph

Get Graph Data

query GetKnowledgeGraph {
  getKnowledgeGraph {
    nodes {
      id
      labels
      properties
    }
    edges {
      id
      type
      source
      target
      properties
    }
  }
}

Error Handling

Standard Error Format

{
  "errors": [
    {
      "message": "Error description",
      "extensions": {
        "code": "ERROR_CODE",
        "details": {}
      }
    }
  ]
}

Common Error Codes

UNAUTHENTICATED: Missing or invalid JWT token
FORBIDDEN: Insufficient permissions
NOT_FOUND: Resource doesn't exist
BAD_USER_INPUT: Invalid input data
INTERNAL_SERVER_ERROR: Server error

Rate Limiting

API is rate-limited to prevent abuse:

Authenticated: 1000 requests per hour
Unauthenticated: 100 requests per hour

GraphQL Playground

Development playground available at:

http://localhost:3002/graphql

Features:

Schema exploration
Query building
Mutation testing
Documentation browser

TypeScript Client

Generated Types

All types are auto-generated from the schema:

import type {
  Member,
  Persona,
  MembershipProof,
  GetCurrentUserQuery,
  BootstrapUserMutation,
} from '@repo/graphql';

Using Apollo Client

import { ApolloClient, InMemoryCache } from '@apollo/client';

const client = new ApolloClient({
  uri: process.env.NEXT_PUBLIC_GRAPHQL_URL,
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${token}`,
  },
});

Best Practices

Caching

Use Apollo Client caching for optimal performance:

const cache = new InMemoryCache({
  typePolicies: {
    Member: {
      keyFields: ['id'],
    },
    Persona: {
      keyFields: ['id'],
    },
  },
});

Error Handling

Always handle errors gracefully:

try {
  const { data } = await client.mutate({
    mutation: BOOTSTRAP_USER,
  });
} catch (error) {
  if (error.graphQLErrors) {
    // Handle GraphQL errors
  }
  if (error.networkError) {
    // Handle network errors
  }
}

Optimistic Updates

Improve UX with optimistic responses:

await client.mutate({
  mutation: UPDATE_PERSONA,
  variables: { id, name },
  optimisticResponse: {
    updatePersona: {
      __typename: 'Persona',
      id,
      name,
    },
  },
});

Support

For API support:

API Reference

On this page