Reference
Notes:
- The regular methods take payloads objects as input parameters, which are documented for each method. These methods are designed to be easy to use and understand.
- However, if you are already familiar with the XRPL protocol convention, you can use the methods documented in the XRPL Protocol methods section. These methods will directly take transaction payloads as defined in the XRPL Protocol.
Regular methods
acceptNFTOffer
Accepts an existing offer for a Non-Fungible Token (NFT) through the extension.
Request
Mandatory - The function takes a payload of type AcceptNFTOfferRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
NFTokenSellOffer: Identifies the NFTokenOffer that offers to sell the NFToken.NFTokenBuyOffer: Identifies the NFTokenOffer that offers to buy the NFToken.NFTokenBrokerFee: This field is only valid in brokered mode, and specifies the amount that the broker keeps as part of their fee for bringing the two offers together; the remaining amount is sent to the seller of the NFToken being bought.- If specified, the fee must be such that, before applying the transfer fee, the amount that the seller would receive is at least as much as the amount indicated in the sell offer.
- Specified in one of the following formats:
- A string representing the number of XRP to deliver, in drops.
- An object where 'value' is a string representing the number of the token to deliver.
- More technical details about the amount formats can be found here.
interface AcceptNFTOfferRequest extends BaseTransactionRequest {
// Identifies the NFTokenOffer that offers to sell the NFToken.
NFTokenSellOffer?: string;
// Identifies the NFTokenOffer that offers to buy the NFToken.
NFTokenBuyOffer?: string;
// This field is only valid in brokered mode, and specifies the amount that the broker keeps as part of their fee for
// bringing the two offers together; the remaining amount is sent to the seller of the NFToken being bought.
// If specified, the fee must be such that, before applying the transfer fee, the amount that the seller would receive
// is at least as much as the amount indicated in the sell offer.
NFTokenBrokerFee?: Amount;
}
type Amount = {
currency: string;
issuer: string;
value: string;
} | string;
More details about the amount format can be found here.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { acceptNFTOffer } from "@gemwallet/api";
const payload = {
NFTokenSellOffer: "Replace me!",
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
acceptNFTOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, acceptNFTOffer } from "@gemwallet/api";
function App() {
const handleAcceptOffer = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
NFTokenSellOffer: "Replace me!",
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
acceptNFTOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleAcceptOffer}>Accept NFT Offer</button>
</div>
);
}
export default App;
burnNFT
Burns a Non-Fungible Token (NFT) through the extension.
Request
Mandatory - The function takes a payload of type BurnNFTRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
NFTokenID: The NFToken to be removed by this transaction.owner: The owner of the NFToken to burn.- Only used if that owner is different than the account sending this transaction.
- The issuer or authorized minter can use this field to burn NFTs that have the lsfBurnable flag enabled.
interface BurnNFTRequest extends BaseTransactionRequest {
// The NFToken to be removed by this transaction.
NFTokenID: string;
// The owner of the NFToken to burn. Only used if that owner is different than the account sending this transaction.
// The issuer or authorized minter can use this field to burn NFTs that have the lsfBurnable flag enabled.
owner?: string;
}
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { burnNFT } from "@gemwallet/api";
const payload = {
NFTokenID: "Replace me!",
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
burnNFT(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, burnNFT } from "@gemwallet/api";
function App() {
const handleBurnNFT = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
NFTokenID: "Replace me!",
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
burnNFT(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleBurnNFT}>Burn NFT</button>
</div>
);
}
export default App;
cancelNFTOffer
Cancels an existing offer for a Non-Fungible Token (NFT) through the extension.
Request
Mandatory - The function takes a payload of type CancelNFTOfferRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
NFTokenOffers: An array of IDs of the NFTokenOffer objects to cancel.- Each entry must be a different object ID of an NFTokenOffer object; the transaction is invalid if the array contains duplicate entries.
interface CancelNFTOfferRequest extends BaseTransactionRequest {
// An array of IDs of the NFTokenOffer objects to cancel (not the IDs of NFToken objects, but the IDs of the
// NFTokenOffer objects). Each entry must be a different object ID of an NFTokenOffer object; the transaction is
// invalid if the array contains duplicate entries.
NFTokenOffers: string[];
}
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { cancelNFTOffer } from "@gemwallet/api";
const payload = {
NFTokenOffers: ["Replace me!"],
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
cancelNFTOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, cancelNFTOffer } from "@gemwallet/api";
function App() {
const handleCancelNFTOffer = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
NFTokenOffers: ["Replace me!"],
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
cancelNFTOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleCancelNFTOffer}>Cancel NFT Offer!</button>
</div>
);
}
export default App;
cancelOffer
Cancels an existing offer through the extension.
Request
Mandatory - The function takes a payload of type CancelOfferRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
offerSequence: The sequence number (or Ticket number) of a previous OfferCreate transaction.- If specified, cancel any offer object in the ledger that was created by that transaction.
- It is not considered an error if the offer specified does not exist.
interface CancelOfferRequest extends BaseTransactionRequest {
// The sequence number (or Ticket number) of a previous OfferCreate transaction. If specified, cancel any offer object
// in the ledger that was created by that transaction. It is not considered an error if the offer specified does not
// exist.
offerSequence: number;
}
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { cancelOffer } from "@gemwallet/api";
const payload = {
offerSequence: 0, // Replace me!
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
cancelOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, cancelOffer } from "@gemwallet/api";
function App() {
const handleCancelOffer = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
offerSequence: 0, // Replace me!
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
cancelOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleCancelOffer}>Cancel Offer</button>
</div>
);
}
export default App;
createNFTOffer
Creates a new offer for a Non-Fungible Token (NFT) through the extension.
Request
Mandatory - The function takes a payload of type CreateNFTOfferRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
NFTokenID: Identifies the NFTokenID of the NFToken object that the offer references.amount: Indicates the amount expected or offered for the Token.- The amount must be non-zero, except when this is a sell offer and the asset is XRP. This would indicate that the current owner of the token is giving it away free, either to anyone at all, or to the account identified by the Destination field.
- Specified in one of the following formats:
- A string representing the number of XRP to deliver, in drops.
- An object where 'value' is a string representing the number of the token to deliver.
- More technical details about the amount formats can be found here.
owner: Indicates the AccountID of the account that owns the corresponding NFToken.- If the offer is to buy a token, this field must be present and it must be different than Account (since an offer to buy a token one already holds is meaningless).
- If the offer is to sell a token, this field must not be present, as the owner is, implicitly, the same as Account (since an offer to sell a token one doesn't already hold is meaningless).
expiration: Indicates the time after which the offer will no longer be valid. The value is the number of seconds since the Ripple Epoch.destination: If present, indicates that this offer may only be accepted by the specified account.- Attempts by other accounts to accept this offer MUST fail.
flags: Flags to set on the transaction.
interface CreateNFTOfferRequest extends BaseTransactionRequest {
// Identifies the NFTokenID of the NFToken object that the offer references.
NFTokenID: string;
// Indicates the amount expected or offered for the Token.
// The amount must be non-zero, except when this is a sell offer and the asset is XRP. This would indicate that the
// current owner of the token is giving it away free, either to anyone at all, or to the account identified by the
// Destination field.
amount: Amount;
// Indicates the AccountID of the account that owns the corresponding NFToken.
// If the offer is to buy a token, this field must be present and it must be different than Account (since an offer
// to buy a token one already holds is meaningless).
// If the offer is to sell a token, this field must not be present, as the owner is, implicitly, the same as Account
// (since an offer to sell a token one doesn't already hold is meaningless).
owner?: string;
// Indicates the time after which the offer will no longer be valid. The value is the number of seconds since the
// Ripple Epoch.
expiration?: number;
// If present, indicates that this offer may only be accepted by the specified account. Attempts by other accounts to
// accept this offer MUST fail.
destination?: string;
flags?: CreateNFTOfferFlags;
}
type CreateNFTOfferFlags = {
tfSellNFToken?: boolean;
} | number;
More details about the flags can be found here.
type Amount = {
currency: string;
issuer: string;
value: string;
} | string;
More details about the amount format can be found here.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { createNFTOffer } from "@gemwallet/api";
const payload = {
NFTokenID: "Replace me!",
amount: 50000000, // 50 XRP
fee: "199",
flags: {
tfSellNFToken: true // If enabled, indicates that the offer is a sell offer. Otherwise, it is a buy offer.
},
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
createNFTOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, createNFTOffer } from "@gemwallet/api";
function App() {
const handleCreateNFTOffer = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
NFTokenID: "Replace me!",
amount: 50000000, // 50 XRP
fee: "199",
flags: {
tfSellNFToken: true // If enabled, indicates that the offer is a sell offer. Otherwise, it is a buy offer.
},
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
createNFTOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleCreateNFTOffer}>Create NFT Offer!</button>
</div>
);
}
export default App;
createOffer
Creates a new offer through the extension.
Request
Mandatory - The function takes a payload of type CreateOfferRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
flags: Flags to set on the transaction.expiration: Time after which the Offer is no longer active, in seconds since the Ripple Epoch.offerSequence: An Offer to delete first, specified in the same way as OfferCancel.takerGets: The amount and type of currency being sold, in one of the following formats:- A string representing the number of XRP to deliver, in drops.
- An object where 'value' is a string representing the number of the token to deliver.
- More technical details about the amount formats can be found here.
takerPays: The amount and type of currency being bought, in one of the following formats:- A string representing the number of XRP to deliver, in drops.
- An object where 'value' is a string representing the number of the token to deliver.
- More technical details about the amount formats can be found here.
interface CreateOfferRequest extends BaseTransactionRequest {
flags?: CreateOfferFlags;
// Time after which the Offer is no longer active, in seconds since the Ripple Epoch.
expiration?: number;
// An Offer to delete first, specified in the same way as OfferCancel.
offerSequence?: number;
// The amount and type of currency being sold.
takerGets: Amount;
// The amount and type of currency being bought.
takerPays: Amount;
}
type OfferCreateFlagsInterface = {
tfPassive?: boolean;
tfImmediateOrCancel?: boolean;
tfFillOrKill?: boolean;
tfSell?: boolean;
} | number;
type Amount = {
currency: string;
issuer: string;
value: string;
} | string;
More details about the amount format can be found here.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { createOffer } from "@gemwallet/api";
const payload = {
takerGets: "10000000", // 10 XRP
takerPays: {
currency: "ETH",
issuer: "rnm76Qgz4G9G4gZBJVuXVvkbt7gVD7szey",
value: "0.1"
},
flags: {
tfPassive: true
},
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
createOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, createOffer } from "@gemwallet/api";
function App() {
const handleCreateOffer = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
takerGets: "10000000", // 10 XRP
takerPays: {
currency: "ETH",
issuer: "rnm76Qgz4G9G4gZBJVuXVvkbt7gVD7szey",
value: "0.1"
},
flags: {
tfPassive: true
},
fee: "199",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
createOffer(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleCreateOffer}>Create Offer</button>
</div>
);
}
export default App;
getAddress
Retrieves the wallet address associated with the extension.
Request
This function does not require any parameters.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:address: The classic address of the wallet.
type: "response";
result: {
address: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { getAddress } from "@gemwallet/api";
getAddress().then((response) => {
console.log(response.result?.address);
});
Here is an example with a React web application:
import { isInstalled, getAddress } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
getAddress().then((response) => {
console.log(`Your address: ${response.result?.address}`);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
getNetwork
Retrieves the network associated with the extension.
Request
This function does not require any parameters.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:network: The network name as a string.
Returns:
Mainnetif the user is connected to themain network.Testnetif the user is connected to thetest network.Devnetif the user is connected to thedeveloper network.AMM-Devnetif the user is connected to theAMM Devnet.
type: "response";
result: {
network: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { getNetwork } from "@gemwallet/api";
getNetwork().then((response) => {
console.log(response.result?.network);
});
Here is an example with a React web application:
import { isInstalled, getNetwork } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
getNetwork().then((response) => {
console.log(`Your network: ${response.result?.network}`);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
getNFT
Retrieves NFTs associated with the wallet.
Request
Optional - This function requires an optional payload parameter which has properties defined by GetNFTRequest.
limit: The maximum number of NFTs to return.marker: A value from a previous paginated response. This is used to resume retrieving data where the previous response left off.
interface GetNFTRequest {
// Limit the number of NFTokens to retrieve.
limit?: number;
// Value from a previous paginated response. Resume retrieving data where that response left off.
marker?: unknown;
}
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:account_nfts: AccountNFToken[] - An array of NFTs associated with the wallet.marker: A value to be used as a marker in a subsequent request.
type: "response";
result: {
account_nfts: AccountNFToken[];
marker: unknown;
}
interface AccountNFToken {
Flags: number;
Issuer: string;
NFTokenID: string;
NFTokenTaxon: number;
URI?: string;
nft_serial: number;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { getNFT } from "@gemwallet/api";
getNFT({ limit: 10 }).then((response) => {
console.log(response.result?.account_nfts);
});
Here is an example of implementation:
import { isInstalled, getNFT } from "@gemwallet/api";
function App() {
const handleNFTs = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
getNFT().then((result) => {
console.log("Your NFTs: ", result.result?.account_nfts);
});
}
});
};
return (
<div className="App">
<button onClick={handleNFTs}>Show my NFTs!</button>
</div>
);
}
export default App;
getPublicKey
Retrieves the public key associated with the wallet.
Request
This function does not require any parameters.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:address: Classic address of the wallet.publicKey: Public key of the wallet.
type: "response";
result: {
address: string;
publicKey: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { getPublicKey } from "@gemwallet/api";
getPublicKey().then((response) => {
console.log(`${response.result?.address} - ${response.result?.publicKey}`);
});
Here is an example with a React web application:
import { isInstalled, getPublicKey } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
getPublicKey().then((response) => {
console.log(
`${response.result?.address} - ${response.result?.publicKey}`
);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
isInstalled
Checks if the GemWallet extension is installed in the user's browser.
tip
We definitely recommend that you check if the user has GemWallet installed before using any of the other methods available.
Request
This function does not require any parameters.
Response
result: {
isInstalled: boolean;
}
isInstalled:trueif the user has GemWallet extension installed,falseotherwise.
Examples
import { isInstalled } from "@gemwallet/api";
isInstalled().then((response) => {
console.log(response.result.isInstalled);
});
Here is an example with a React web application:
import { isInstalled } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (!response.result.isInstalled) {
console.log("GemWallet is not installed");
} else {
console.log("GemWallet is installed");
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
mintNFT
Mints a new Non-Fungible Token (NFT) through the extension.
Request
Mandatory - The function takes a payload of type MintNFTRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
flags: Flags to be set on the transaction.issuer: Indicates the issuer of the token.- Should only be specified if the account executing the transaction is not the Issuer of the token, e.g. when minting on behalf of another account.
NFTokenTaxon: Indicates the taxon associated with this token.- The taxon is generally a value chosen by the minter of the token and a given taxon may be used for multiple tokens.
- The implementation reserves taxon identifiers greater than or equal to 2147483648 (0x80000000).
- If you have no use for this field, set it to 0.
transferFee: Specifies the fee charged by the issuer for secondary sales of the Token, if such sales are allowed.- Valid values for this field are between 0 and 50000 inclusive, allowing transfer rates between 0.000% and 50.000% in increments of 0.001%.
- This field must NOT be present if the tfTransferable flag is not set.
URI: URI that points to the data and/or metadata associated with the NFT.- This field need not be an HTTP or HTTPS URL; it could be an IPFS URI, a magnet link, immediate data encoded as an RFC2379 "data" URL, or even an opaque issuer-specific encoding.
- The URI is NOT checked for validity, but the field is limited to a maximum length of 256 bytes.
- This field must be hex-encoded.
interface MintNFTRequest extends BaseTransactionRequest {
flags?: MintNFTFlags;
// Indicates the issuer of the token.
// Should only be specified if the account executing the transaction is not the Issuer of the token, e.g. when minting on behalf of another account.
issuer?: string;
// Indicates the taxon associated with this token. The taxon is generally a value chosen by the minter of the token
// and a given taxon may be used for multiple tokens. The implementation reserves taxon identifiers greater than or
// equal to 2147483648 (0x80000000). If you have no use for this field, set it to 0.
NFTokenTaxon: number;
// Specifies the fee charged by the issuer for secondary sales of the Token, if such sales are allowed. Valid values
// for this field are between 0 and 50000 inclusive, allowing transfer rates between 0.000% and 50.000% in increments
// of 0.001%. This field must NOT be present if the tfTransferable flag is not set.
transferFee?: number;
// URI that points to the data and/or metadata associated with the NFT. This field need not be an HTTP or HTTPS URL;
// it could be an IPFS URI, a magnet link, immediate data encoded as an RFC2379 "data" URL, or even an opaque
// issuer-specific encoding. The URI is NOT checked for validity, but the field is limited to a maximum length of
// 256 bytes.
// This field must be hex-encoded.
URI?: string;
}
type MintNFTFlags = {
tfBurnable?: boolean;
tfOnlyXRP?: boolean;
tfTrustLine?: boolean;
tfTransferable?: boolean;
} | number;
More details about the flags can be found here.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:NFTokenID: The ID of the NFT.hash: The hash of the transaction.
type: "response";
result: {
NFTokenID: string;
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { mintNFT } from "@gemwallet/api";
const payload = {
URI: "4d696e746564207468726f7567682047656d57616c6c657421",
flags: {
tfOnlyXRP: true,
tfTransferable: true
},
fee: "199",
transferFee: 3000, // 3%,
NFTokenTaxon: 0,
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
mintNFT(payload).then((response) => {
console.log("NFT ID: ", response.result?.NFTokenID);
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, mintNFT } from "@gemwallet/api";
function App() {
const handleMintNFT = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
URI: "4d696e746564207468726f7567682047656d57616c6c657421",
flags: {
tfOnlyXRP: true,
tfTransferable: true
},
fee: "199",
transferFee: 3000, // 3%,
NFTokenTaxon: 0,
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
mintNFT(payload).then((response) => {
console.log("NFT ID: ", response.result?.NFTokenID);
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleMintNFT}>Mint NFT!</button>
</div>
);
}
export default App;
sendPayment
Initiates a payment transaction through the extension.
Request
Mandatory - The function takes a payload object as an input parameter, which has properties defined by SendPaymentRequest.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
amount: The amount to deliver, in one of the following formats:- A string representing the number of XRP to deliver, in drops.
- An object where 'value' is a string representing the number of the token to deliver.
- More technical details about the amount formats can be found here.
destination: The unique address of the account receiving the payment.destinationTag: The destination tag to attach to the transaction.flags: Flags to set on the transaction.
export interface SendPaymentRequest extends BaseTransactionRequest {
// The amount to deliver, in one of the following formats:
// - A string representing the number of XRP to deliver, in drops.
// - An object where 'value' is a string representing the number of the token to deliver.
amount: Amount;
// The unique address of the account receiving the payment
destination: string;
// The destination tag to attach to the transaction
destinationTag?: number;
// Flags to set on the transaction
flags?: PaymentFlags;
}
type Amount = {
currency: string;
issuer: string;
value: string;
} | string;
More details about the amount format can be found here.
interface Memo {
memo: {
memoType?: string;
memoData?: string;
memoFormat?: string;
};
}
More technical details about the memos can be found here.
type PaymentFlags = {
tfNoDirectRipple?: boolean;
tfPartialPayment?: boolean;
tfLimitQuality?: boolean;
} | number;
More details about the flags can be found here.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { sendPayment } from "@gemwallet/api";
const payload = {
amount: "1000000", // In drops (1 XRP)
destination: "rLWQskMM8EoPxaLsmuQxE5rYeP4uX7dhym",
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f",
},
},
],
destinationTag: 12,
fee: "199",
flags: {
tfNoDirectRipple: false,
tfPartialPayment: false,
tfLimitQuality: false,
},
};
sendPayment(payload).then((response) => {
console.log(response.result?.hash);
});
Here is an example for an XRP Payment with a React web application:
import { isInstalled, sendPayment } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payment = {
amount: "1000000", // In drops (1 XRP)
destination: "rLWQskMM8EoPxaLsmuQxE5rYeP4uX7dhym",
};
sendPayment(payment).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
Here is an example for an ETH Payment with a React web application:
import { isInstalled, sendPayment } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payment = {
amount: {
currency: "ETH",
value: "0.01", // In currency
issuer: "rnm76Qgz4G9G4gZBJVuXVvkbt7gVD7szey",
},
destination: "rLWQskMM8EoPxaLsmuQxE5rYeP4uX7dhym",
};
sendPayment(payment).then((trHash) => {
console.log("Transaction Hash: ", trHash);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
setAccount
Sets an account through the extension.
Request
Mandatory - The function takes a payload of type SetAccountRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
flags: Flags to set on the transaction.clearFlag: Unique identifier of a flag to disable for this account.domain: The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase.- Cannot be more than 256 bytes in length.
emailHash: An arbitrary 128-bit value.- Conventionally, clients treat this as the md5 hash of an email address to use for displaying a Gravatar image.
messageKey: Public key for sending encrypted messages to this account.- To set the key, it must be exactly 33 bytes, with the first byte indicating the key type: 0x02 or 0x03 for secp256k1 keys, 0xED for Ed25519 keys.
- To remove the key, use an empty value.
NFTokenMinter: Another account that can mint NFTokens for you.setFlag: Integer flag to enable for this account.transferRate: The fee to charge when users transfer this account's tokens, represented as billionths of a unit.- Cannot be more than 2000000000 or less than 1000000000, except for the special case 0 meaning no fee.
tickSize: Tick size to use for offers involving a currency issued by this address.- The exchange rates of those offers is rounded to this many significant digits.
- Valid values are 3 to 15 inclusive, or 0 to disable.
interface SetAccountRequest extends BaseTransactionRequest {
flags?: SetAccountFlags;
// Unique identifier of a flag to disable for this account.
clearFlag?: number;
// The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase.
// Cannot be more than 256 bytes in length.
domain?: string;
// An arbitrary 128-bit value. Conventionally, clients treat this as the md5 hash of an email address to use for
// displaying a Gravatar image.
emailHash?: string;
// Public key for sending encrypted messages to this account. To set the key, it must be exactly 33 bytes, with the
// first byte indicating the key type: 0x02 or 0x03 for secp256k1 keys, 0xED for Ed25519 keys. To remove the key, use
// an empty value.
messageKey?: string;
// Another account that can mint NFTokens for you.
NFTokenMinter?: string;
// Integer flag to enable for this account.
setFlag?: AccountSetAsfFlags;
// The fee to charge when users transfer this account's tokens, represented as billionths of a unit. Cannot be more
// than 2000000000 or less than 1000000000, except for the special case 0 meaning no fee.
transferRate?: number;
// Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is
// rounded to this many significant digits. Valid values are 3 to 15 inclusive, or 0 to disable.
tickSize?: number;
}
type AccountSetFlagsInterface = {
tfRequireDestTag?: boolean;
tfOptionalDestTag?: boolean;
tfRequireAuth?: boolean;
tfOptionalAuth?: boolean;
tfDisallowXRP?: boolean;
tfAllowXRP?: boolean;
} | number;
enum AccountSetAsfFlags {
asfRequireDest = 1,
asfRequireAuth = 2,
asfDisallowXRP = 3,
asfDisableMaster = 4,
asfAccountTxnID = 5,
asfNoFreeze = 6,
asfGlobalFreeze = 7,
asfDefaultRipple = 8,
asfDepositAuth = 9,
asfAuthorizedNFTokenMinter = 10,
asfDisallowIncomingNFTokenOffer = 12,
asfDisallowIncomingCheck = 13,
asfDisallowIncomingPayChan = 14,
asfDisallowIncomingTrustline = 15
}
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { setAccount } from "@gemwallet/api";
const payload = {
emailHash: "1D1382344586ECFF844DACFF698C2EFB",
fee: "199",
flags: {
tfAllowXRP: true
},
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
setAccount(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, setAccount } from "@gemwallet/api";
function App() {
const handleSetAccount = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const payload = {
emailHash: "1D1382344586ECFF844DACFF698C2EFB",
fee: "199",
flags: {
tfAllowXRP: true
},
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f"
}
}
]
};
setAccount(payload).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleSetAccount}>Set Account</button>
</div>
);
}
export default App;
setTrustLine
Adds or edits a trustline within the wallet.
Request
Mandatory - The function takes a payload of type SetTrustlineRequest as an input parameter.
- All the fields from
BaseTransactionRequest.- See BaseTransactionRequest for more details.
limitAmount: The maximum amount of currency that can be exchanged to the trustline.- More technical details about the amount formats can be found here.
flags: Flags to set on the transaction.
interface SetTrustlineRequest extends BaseTransactionRequest {
// The maximum amount of currency that can be exchanged to the trustline
limitAmount: IssuedCurrencyAmount;
// Flags to set on the transaction
flags?: TrustSetFlags;
}
interface IssuedCurrencyAmount {
currency: string;
issuer: string;
value: string;
}
More technical details about the currency amount formats can be found here.
interface Memo {
memo: {
memoType?: string;
memoData?: string;
memoFormat?: string;
};
}
More technical details about the memos can be found here.
type TrustSetFlags = {
tfSetfAuth?: boolean;
tfSetNoRipple?: boolean;
tfClearNoRipple?: boolean;
tfSetFreeze?: boolean;
tfClearFreeze?: boolean;
} | number;
More details about the flags can be found here.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { setTrustline } from "@gemwallet/api";
const trustline = {
limitAmount: {
currency: "ETH",
issuer: "rnm76Qgz4G9G4gZBJVuXVvkbt7gVD7szey",
value: "10000000",
},
memos: [
{
memo: {
memoType: "4465736372697074696f6e",
memoData: "54657374206d656d6f",
},
},
],
fee: "199",
flags: {
tfClearFreeze: false,
tfClearNoRipple: false,
tfSetFreeze: true,
tfSetNoRipple: true,
tfSetfAuth: false,
},
};
setTrustline(trustline).then((response) => {
console.log(response.result?.hash);
});
Here is an example with a React web application:
import { isInstalled, addTrustline } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const transaction = {
limitAmount: {
currency: "ETH",
issuer: "rnm76Qgz4G9G4gZBJVuXVvkbt7gVD7szey",
value: "10000000",
},
};
addTrustline(transaction).then((response) => {
console.log("Transaction Hash: ", response.result?.hash);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
signMessage
Signs a message using the private key of the user's wallet.
Request
The function takes a message string as an input parameter.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:signedMessage: The signed message.
type: "response";
result: {
signedMessage: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { signMessage } from "@gemwallet/api";
const message = "Hello, World!";
signMessage(message).then((response) => {
console.log(response.result?.signedMessage);
});
Here is an example with a React web application:
import { isInstalled, signMessage } from "@gemwallet/api";
function App() {
const handleConnect = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
signMessage("The message I want to get signed").then((response) => {
console.log("Signed message: ", response.result?.signedMessage);
});
}
});
};
return (
<div className="App">
<button onClick={handleConnect}>Click me!</button>
</div>
);
}
export default App;
XRPL Protocol methods
submitTransaction
Submits a transaction payload request to the XRPL network via the extension. The transaction will be automatically autofilled, signed and submitted.
Request
Mandatory - The function takes a payload of type SubmitTransactionRequest as an input parameter.
transaction: The transaction payload to submit to the XRPL network.
interface SubmitTransactionRequest {
transaction: Transaction;
}
The Transaction type is defined here.
Notes:
- If the transaction field
Accountis not set, the account of the user's wallet will be used.
Response
The response is a Promise which resolves to an object with a type and result property.
type:"response" | "reject"result:hash: The hash of the transaction.
type: "response";
result: {
hash: string;
}
or
type: "reject";
result: undefined;
Error Handling
In case of error, the error will be thrown.
Examples
import { submitTransaction } from "@gemwallet/api";
const transaction = {
TransactionType: "Payment",
Destination: "rhikRdkFw28csKw9z7fVoBjWncz1HSoQij",
Amount: "100000",
Memos: [
{
Memo: {
MemoData: "54657374206D656D6F",
MemoType: "4465736372697074696F6E"
}
}
]
};
submitTransaction({ transaction }).then((response) => {
console.log(response.result?.hash);
}).catch((error) => {
console.error("Transaction submission failed", error);
});
Here is an example with a React web application:
import { submitTransaction, isInstalled } from "@gemwallet/api";
function App() {
const handleTransaction = () => {
isInstalled().then((response) => {
if (response.result.isInstalled) {
const transaction = {
TransactionType: "Payment",
Destination: "rhikRdkFw28csKw9z7fVoBjWncz1HSoQij",
Amount: "100000",
Memos: [
{
Memo: {
MemoData: "54657374206D656D6F",
MemoType: "4465736372697074696F6E"
}
}
]
};
submitTransaction({ transaction }).then((response) => {
console.log("Transaction hash: ", response.result?.hash);
}).catch((error) => {
console.error("Transaction submission failed", error);
});
}
});
};
return (
<div className="App">
<button onClick={handleTransaction}>Submit Transaction</button>
</div>
);
}
export default App;
Other
BaseTransactionRequest
All the Request interfaces that extend the BaseTransactionRequest interface also include the following fields:
fee: Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network.- Some transaction types have different minimum requirements.
- More technical details about the drops can be found here.
sequence: The sequence number of the account sending the transaction.- A transaction is only valid if the Sequence number is exactly 1 greater than the previous transaction from the same account.
- The special case 0 means the transaction is using a Ticket instead.
accountTxnID: Hash value identifying another transaction.- If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash.
lastLedgerSequence: Highest ledger index this transaction can appear in.- Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected.
memos: Additional arbitrary information used to identify this transaction.- Each attribute of each memo must be hex encoded.
- More technical details about the memos can be found here.
signers: Array of objects that represent a multi-signature which authorizes this transaction.- More technical details about the signers can be found here.
sourceTag: Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made.- Conventionally, a refund should specify the initial payment's SourceTag as the refund payment's DestinationTag.
signingPubKey: Hex representation of the public key that corresponds to the private key used to sign this transaction.- If an empty string, indicates a multi-signature is present in the Signers field instead.
ticketSequence: The sequence number of the ticket to use in place of a Sequence number.- If this is provided, Sequence must be 0.
- Cannot be used with AccountTxnID.
txnSignature: The signature that verifies this transaction as originating from the account it says it is from.
interface BaseTransactionRequest {
// Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network.
// Some transaction types have different minimum requirements.
fee?: string;
// The sequence number of the account sending the transaction. A transaction is only valid if the Sequence number is
// exactly 1 greater than the previous transaction from the same account. The special case 0 means the transaction is
// using a Ticket instead.
sequence?: number;
// Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's
// previously-sent transaction matches the provided hash.
accountTxnID?: string;
// Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long
// the transaction can wait to be validated or rejected.
lastLedgerSequence?: number;
// Additional arbitrary information used to identify this transaction.
// Each attribute of each memo must be hex encoded.
memos?: Memo[];
// Array of objects that represent a multi-signature which authorizes this transaction.
signers?: Signer[];
// Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is
// made. Conventionally, a refund should specify the initial payment's SourceTag as the refund payment's
// DestinationTag.
sourceTag?: number;
// Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty
// string, indicates a multi-signature is present in the Signers field instead.
signingPubKey?: string;
// The sequence number of the ticket to use in place of a Sequence number. If this is provided, Sequence must be 0.
// Cannot be used with AccountTxnID.
ticketSequence?: number;
// The signature that verifies this transaction as originating from the account it says it is from.
txnSignature?: string;
}
interface Memo {
memo: {
memoType?: string;
memoData?: string;
memoFormat?: string;
};
}
More technical details about the memos can be found here.
interface Signer {
signer: {
account: string;
txnSignature: string;
signingPubKey: string;
};
}
More technical details about the signers can be found here.