The Gateway Provider
The GatewayProvider is a React component that gives children access to the GatewayContext through the useGateway function. This component holds the state for a given Gateway Token or Gateway Token request.
Warning: The Ethereum integration is in alpha and is subject to change.
import { GatewayProvider } from "@civic/ethereum-gateway-react";
<GatewayProvider
signer={signer}
provider={provider}
gatekeeperNetwork={gatekeeperNetwork}
>
</GatewayProvider>
Property | Description | Type |
signer | Signer from ethers | |
provider | Provider from ethers | |
gatekeeperNetwork | The address of the gatekeeper network. This needs to match the network within which the Civic gatekeeper issues tokens. |
The React component exposes the process status of a gateway token request, as well as the token status itself. It also provides a function to request a new gateway token. These can be accessed through the
useGateway
hook:import { useGateway } from "@civic/ethereum-gateway-react";
A function is provided to initiate a request for a new gateway token:
const { requestGatewayToken } = useGateway()
This could be triggered by a button, for example:
<button onclick={requestGatewayToken}>Validate your wallet</button>
Calling this function should open an iframe connected to the Civic Gatekeeper, which will guide the user through a flow to verify their identity and other prerequisites:

Besides the
refreshGatewayToken
function, the useGateway
hook also exposes some state variables to indicate the status of the Civic Pass request flows and the state of the token itself.const { gatewayStatus, gatewayToken } = useGateway();
gatewayStatus | Indicates the overall status of the Civic Pass. This should ideally displayed to the user. Some states are linked to an on-chain gateway token, while others indicate progress or error conditions during which a gateway token might not exist. | GatewayStatus from @civic/ethereum-gateway-react |
gatewayToken | Represents the on-chain Ethereum structure for the gateway token. This will only be defined if the on-chain token is ACTIVE and dApp usage should be allowed. If the token does not exist or is in a non-active state (e.g. Frozen), this state variable will be undefined . The dApp could disable certain parts of the UI when gatewayToken is undefined to prevent dApp usage.This complements the on-chain Rust check, but should not replace it. | GatewayToken from @identity.com/gateway-eth-ts |
import { GatewayProvider } from "@civic/solana-gateway-react";
import { Connection, clusterApiUrl } from '@solana/web3.js';
<GatewayProvider
connection={new Connection(clusterApiUrl("mainnet-beta"))}
cluster="mainnet-beta"
wallet={wallet}
gatekeeperNetwork={gatekeeperNetwork}>
</GatewayProvider>
Property | Description | Type |
wallet | An object representing the user's wallet. This may be undefined if a wallet hasn't been connected to the dApp yet. | { publicKey, signTransaction } (see definitions below) |
wallet.publicKey | The user wallet's public key | PublicKey from @solana/web3.js |
wallet.signTransaction | A function that asks the user's wallet to sign a transaction. | (transaction: Transaction) => Promise<Transaction> where Transaction is from @solana/web3.js |
gatekeeperNetwork | The public key of the gatekeeper network. This needs to match the network within which the Civic gatekeeper issues tokens. | PublicKey from @solana/web3.js |
connection | A solana connection to any solana network, with a recommended commitment of 'processed' | Connection from @solana/web3.js |
cluster | the Solana network to use, i.e. devnet, mainnet-beta, testnet. This defaults to mainnet-beta, so should be set if a different connection endpoint is used than mainnet-beta | string |
gatekeeperSendsTransaction | The gatekeeper will send the transaction to the blockchain. Defaults to false . When false , the user will be prompted to sign and send the transaction. This is handled internally by the React Component. To customize this behavior the handleTransaction callback function needs to be provided | string |
handleTransaction | An optional callback function that will invoked with a partially signed transaction for the user to sign and send to the blockchain when the property gatekeeperSendsTransaction is false. | (transaction: Transaction) => Promise<void> |
The React component exposes the process status of a gateway token request, as well as the token status itself. It also provides a function to request a new gateway token. These can be accessed through the
useGateway
hook:import { useGateway } from "@civic/solana-gateway-react";
A function is provided to initiate a request for a new gateway token:
const { requestGatewayToken } = useGateway()
This could be triggered by a button, for example:
<button onclick={requestGatewayToken}>Validate your wallet</button>
Calling this function should open an iframe connected to the Civic Gatekeeper, which will guide the user through a flow to verify their identity and other prerequisites:

Besides the
refreshGatewayToken
function, the useGateway
hook also exposes some state variables to indicate the status of the Civic Pass request flows and the state of the token itself.const { gatewayStatus, gatewayToken } = useGateway();
gatewayStatus | Indicates the overall status of the Civic Pass. This should ideally displayed to the user. Some states are linked to an on-chain gateway token, while others indicate progress or error conditions during which a gateway token might not exist. | GatewayStatus from @civic/solana-gateway-react |
gatewayToken | Represents the on-chain Solana structure for the gateway token. This will only be defined if the on-chain token is ACTIVE and dApp usage should be allowed. If the token does not exist or is in a non-active state (e.g. Frozen), this state variable will be undefined . The dApp could disable certain parts of the UI when gatewayToken is undefined to prevent dApp usage.This complements the on-chain Rust check, but should not replace it. | GatewayToken from @identity.com/solana-gateway-ts |
The following is a list of all the possible states of the Civic Pass
Statuses where a Civic Pass exists
Status | Description | Behaviour when triggered |
ACTIVE | The Civic Pass is Active. The user can trade. | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |
EXPIRED | The Civic Pass has expired An IP check and proof of wallet ownership are required to refresh it. | Proof of wallet ownership is automatically initiated |
FROZEN | The Pass has been frozen, for example because the user connected from a blocked IP | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |
REVOKED | The Pass has been revoked, for example because the user connected from a banned IP | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |
Status where a Civic Pass may not exist yet
Status | Description | Behaviour when triggered |
UNKNOWN | No user wallet is connected or no gatekeeper network set | None |
CHECKING | Checking whether a Pass exists for the connected wallet. | None |
NOT_REQUESTED | The wallet is connected but no Pass has been requested yet. | Opens the Civic Pass modal dialog and initiates the token request flow |
COLLECTING_USER_INFORMATION | The required user information is being collected. Depending on the Network configured, this ranges from a simple CAPTCHA to full KYC. | Opens the Civic Pass modal dialog and resumes the collection of the required information. |
VALIDATING_USER_INFORMATION | The user's identity information has been collected successfully and is being verified.
This status is only available when KYC is in progress and only when the user has chosen to do KYC via on their browser. I.e. not relevant for the Ignite Pass that is used with CandyMachine v2. | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |
USER_INFORMATION_VALIDATED | The user's identity has been validated.
This status is only available when KYC is in progress and only when the user has chosen to do KYC via on their browser. I.e. not relevant for the Ignite Pass that is used with CandyMachine v2. | Opens the Civic Pass modal dialog and asks the user to re-authenticate so that the request process can proceed. |
USER_INFORMATION_REJECTED | The user's identity verification request has been rejected.
This status is only available when KYC is in progress and only when the user has chosen to do KYC via on their browser. I.e. not relevant for the Ignite Pass that is used with CandyMachine v2. | Opens the Civic Pass modal displaying the reasons for the rejection ( for example blurry document scan). |
CONFIRM_WALLET_TRANSACTION | The user needs to confirm wallet ownership on their wallet | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |
IN_REVIEW | The Civic Pass has been requested and the Gatekeeper is reviewing the request | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |

Modal for CONFIRM_WALLET_TRANSACTION status
Error statuses
Status | Description | Behaviour when triggered |
LOCATION_NOT_SUPPORTED | The user's location is not currently supported | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |
ERROR | There was an unexpected error requesting a Civic Pass. | Opens the Civic Pass modal dialog and the user can restart the process. |
REJECTED | The token requests has been rejected by the Gatekeeper | Opens the Civic Pass modal dialog with a user-friendly explanation of the status. |

Modal for LOCATION_NOT_SUPPORTED
Last modified 2mo ago