ƒxyzƒxyz Network

API Reference

GraphQL API documentation for ƒxyz Network

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,
    },
  },
});

Bridge (Fiat Ramps)

The API app also exposes authenticated REST endpoints under /api/bridge/* for Bridge.xyz flows (KYC, pay-ins, pay-outs). These use the same JWT auth described above and enforce persona ownership checks.

GraphQL: Bridge Customer Management

Create and list Bridge customers through GraphQL:

mutation CreateBridgeCustomer($input: CreateBridgeCustomerInput!) {
  createBridgeCustomer(input: $input) {
    id
    bridgeId
    status
    type
    hasBridgeIntegration
    needsKyc
    capabilities {
      payin_fiat
      payout_fiat
    }
  }
}
query GetBridgeCustomers {
  getBridgeCustomers {
    id
    bridgeId
    email
    status
    needsKyc
  }
}

Link an existing Bridge customer to a persona:

mutation ConnectPersonaToBridgeKyc($personaId: ID!, $bridgeCustomerId: String!, $kycStatus: String!) {
  connectPersonaToBridgeKyc(
    personaId: $personaId
    bridgeCustomerId: $bridgeCustomerId
    kycStatus: $kycStatus
  )
}

REST: Bridge Endpoints

Base URL: https://api.fxyz.network/api/bridge

  • POST /kyc-links - Create KYC/KYB link. Body: full_name, email, type (individual or business), optional endorsements, redirect_uri, personaId.
  • GET /kyc-links?id=... - Fetch a KYC link by id.
  • GET /customers/{customerId}/kyc-link?endorsement=... - Fetch a KYC link for an existing customer.
  • GET /virtual-accounts - List virtual accounts for the authenticated user.
  • POST /virtual-accounts - Create a virtual account. Body: bridgeCustomerId, destinationWalletAddress, optional currency, destinationPaymentRail, destinationCurrency.
  • GET /external-accounts - List linked bank accounts.
  • POST /external-accounts - Create a bank account. Body: bridgeCustomerId, account_type, currency, bank_name, plus account-specific fields.
  • DELETE /external-accounts?bridgeCustomerId=...&accountId=... - Remove a linked bank account.
  • GET /transfers - List pay-in transfers for owned customers.
  • POST /transfers - Create a pay-in transfer. Body: bridgeCustomerId, amount, destinationAddress, optional currency, sourceRail.
  • GET /transfers/{transferId} - Get transfer details.
  • POST /liquidation - Create an off-ramp transfer. Body: bridgeCustomerId, amount, destinationAccountId, optional destinationType, sourceCurrency, destinationCurrency, sourceChain.
  • GET /liquidations - List off-ramp history stored in Neo4j.

Support

For API support:

Account Settings

Link accounts, upgrade from guest, manage personas, and configure your fXYZ Network preferences.

Technical Documentation

Deep dive into ƒxyz Network's technical implementation

On this page

API ReferenceEndpointAuthenticationJWT TokensGetting a TokenCore MutationsBootstrap UserIssue MembershipMint My MembershipGenerate Membership ProofCore QueriesGet Current UserGet Member by IDGet PersonaPersona ManagementCreate PersonaUpdate PersonaSet Active PersonaKnowledge GraphGet Graph DataError HandlingStandard Error FormatCommon Error CodesRate LimitingGraphQL PlaygroundTypeScript ClientGenerated TypesUsing Apollo ClientBest PracticesCachingError HandlingOptimistic UpdatesBridge (Fiat Ramps)GraphQL: Bridge Customer ManagementREST: Bridge EndpointsSupport