Skip to main content
The allowlist permits an address to deposit into a gtoken’s backing vault. Your organization must have access to the selected yield source. Keep your Ground API key on your backend.

Add an address

Use the catalogue’s id as gVaultId and the deposit receiver as customerAddress. From your backend, fetch the authorization:
The authorization binds your organization, the address, the access contract, and the chain. It expires after five minutes. The address that will deposit or hold shares must authorize the request.

Externally owned account (EOA)

Have the wallet at customerAddress sign the returned EIP-712 typed data. With an ethers v5 signer for that address:

Contract address, including a custom fee wrapper

Have a signer authorized by your contract sign the same typed data, or produce the signature format your contract accepts. The customerAddress in the request and typed data remains the contract address, not the signer’s address. Your deployed contract must implement ERC-1271:
Ground computes the EIP-712 hash and calls this method on customerAddress. For a valid signature, the method must return 0x1626ba7e; otherwise it must reject the signature. Make sure the contract validates signatures according to its own signer or multisig rules. If your contract accepts a single ECDSA signer, use the signing code above with that authorized signer. A contract without this method cannot establish your organization’s management through this endpoint. Signing the authorization is separate from depositing. Your wallet or wrapper does not submit an allowlist transaction to Ground’s onchain contract. After Ground verifies the signature and completes screening, Ground submits the onchain allowlist transaction. If you create a fee wrapper through POST /v2/fee-wrappers, Ground authorizes that wrapper during provisioning; the ownership-proof flow above applies when you deploy the contract yourself. Return ownershipProof to your backend and submit it before it expires:
A new admission requires a matching completed LOW-risk assessment. The operation is idempotent for the desired state:
  • 200 means processing is complete. Check allowed before depositing.
  • 202 means processing is pending; screening or transaction confirmation may still be in progress. Retry or poll the state.

Verify the effective state

Enable deposits only when allowed is true and processing is complete. A transaction hash alone does not establish access. The organization that establishes verified management keeps removal rights. Other organizations can observe an already-allowed address with canManage: false. An onchain permission without verified customer management is reported as unmanaged. Product and Ground infrastructure addresses are managed through their product workflows. Contact Ground if you need to manage an address already reported as unmanaged.

Remove an address

Only the managing organization can request removal. Poll until allowed becomes false. Removal retains your organization’s management rights. For ground_ustb_v1, removal blocks future deposits and does not block redemption of existing shares. For tempo_earn_v1, removal revokes TIP-403 share-token permission, blocking transfers and redemptions as well as new deposits. Restore permission before the address can transfer or redeem its shares.

Handle failures

An invalid or expired signature returns 400; obtain a fresh authorization and sign it again. 403 means your organization or API key lacks access. 404 means the source was not found. 409 means the operation is unsupported or conflicts with an unresolved update. Read the current state before retrying a temporary 503 failure. API reference: add, get, and remove.