Add an address
Use the catalogue’sid as gVaultId and the deposit receiver as
customerAddress. From your backend, fetch the authorization:
Externally owned account (EOA)
Have the wallet atcustomerAddress 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. ThecustomerAddress in the request
and typed data remains the contract address, not the signer’s address. Your
deployed contract must implement ERC-1271:
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:
200means processing is complete. Checkallowedbefore depositing.202means processing is pending; screening or transaction confirmation may still be in progress. Retry or poll the state.
Verify the effective state
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
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 returns400; 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.