sentientpay

Instructions

SentientPay provides card issuance via the Masked Cash API. It lists available card templates, fetches an unsigned Solana USDC transfer transaction for a chosen template, then after the transaction is signed and confirmed you call the issue endpoint to receive the card details.

You can sign the transaction in two ways:

• Server-side (CLI): Use the bundled sign-unsigned-tx.js script with SOLANA_PRIVATE_KEY and SOLANA_RPC_URL in .env. The script signs and submits the tx, then you call issue with the returned signature.
• Frontend: Decode the unsigned transaction in your app, have the user sign and submit with their wallet (e.g. Phantom, Solflare), get the signature, then call issue card with that signature. No private key in .env needed.

End-to-end flow

1. GET available cards → Choose a template (use id and price_usd from the response).
2. GET/POST unsigned transaction with template_id and solana_payer (the wallet that will pay and receive the card) → You receive unsignedTransaction (base64).
3. Sign and submit the transaction:
   • Option A (server): Run node scripts/sign-unsigned-tx.js <unsigned_transaction_base64> (uses SOLANA_PRIVATE_KEY from .env). Output includes signature.
   • Option B (frontend): Decode the base64 tx in your app, have the user sign and submit with their wallet, then use the returned signature.
4. POST issue card with header X-Transaction-Signature: <signature> and body { template_id, solana_payer } → Receive cardId, maskedCardNumber, cardType, creditLimit, and message.

Signing options

• Server-side (CLI): Use sign-unsigned-tx.js with SOLANA_PRIVATE_KEY and SOLANA_RPC_URL in .env. Pass the base64 unsignedTransaction from step 2; the script signs, submits to Solana, and outputs the signature for use with issue-card.
• Frontend: If you want to sign the tx in the frontend (e.g. Phantom, Solflare), decode the unsigned tx, have the user sign and submit in the browser, get the signature, then call issue card with that signature (same template_id and solana_payer). No private key in .env needed for that path.

How to run (implementation)

From the SentientPay directory:

• Get available cards:
  node scripts/get-available-cards.js or npm run available
• Get unsigned transaction:
  node scripts/get-unsigned-tx.js <template_id> <solana_payer> or npm run unsigned -- <template_id> <solana_payer>
• Sign and submit (server-side):
  node scripts/sign-unsigned-tx.js <unsigned_transaction_base64> or npm run sign -- <base64>
  Requires SOLANA_PRIVATE_KEY (and optionally SOLANA_RPC_URL) in .env.
• Issue card:
  node scripts/issue-card.js <template_id> <solana_payer> <signature> or npm run issue -- <template_id> <solana_payer> <signature>

Scripts print JSON to stdout on success, or error JSON to stderr and exit non-zero on failure.

Setup

Set the API key (required for unsigned and issue endpoints):

export SENTIENTPAY_API_KEY=your-sentientpay-api-key

For server-side signing only, also set:

export SOLANA_PRIVATE_KEY=your-base58-private-key
export SOLANA_RPC_URL=https://api.mainnet-beta.solana.com   # optional, this is the default

Endpoint 1 (get available cards) does not require auth.

Functions to call

Flow using function calls

1. Call getAvailableCards() → get list of templates; pick one and note its id (and price_usd).
2. Call getUnsignedTransaction(templateId, solanaPayer) with that template id and the payer’s Solana wallet → you get unsignedTransaction (base64) and metadata.
3. Sign and submit the transaction (one of two ways):
   • Server-side: Call signAndSubmitTransaction(unsignedTransactionBase64) with the base64 string from step 2 → you get signature.
   • Frontend: Decode the base64 tx, have the user sign and submit with their wallet → you get signature.
4. Call issueCard(templateId, solanaPayer, signature) with the same templateId, same solanaPayer, and the signature from step 3 → you get card details (e.g. cardId, maskedCardNumber, creditLimit).