Make your first request

This request checks your endpoint, API key, and HMAC signing without creating a customer or moving funds. You need development credentials from Agio and a Node.js or Bun runtime that can run TypeScript.

Set your credentials

Set AGIO_PARTNER_API_TOKEN and AGIO_PARTNER_CLIENT_SECRET in your server environment. Keep them out of browser code and source control. This example defaults to development; set AGIO_PARTNER_ENDPOINT to the production URL when you are ready to use production credentials.

export AGIO_PARTNER_API_TOKEN='<development API token>'
export AGIO_PARTNER_CLIENT_SECRET='<development signing secret>'

Send a signed query

Save this as partner-request.ts. Serialize the JSON body once, sign that string, and send the same string.

import { createHmac } from "node:crypto";

function requiredEnv(name: string) {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

const endpoint = process.env.AGIO_PARTNER_ENDPOINT ?? "https://dev.api.agiodigital.com/partner/cards/graphql";
const apiToken = requiredEnv("AGIO_PARTNER_API_TOKEN");
const clientSecret = requiredEnv("AGIO_PARTNER_CLIENT_SECRET");

export async function partnerQuery(query: string, variables: Record<string, unknown> = {}) {
  const body = JSON.stringify({ query, variables });
  const timestamp = Date.now().toString();
  const signature = createHmac("sha256", clientSecret).update(`${timestamp}.${body}`).digest("hex");

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-agio-api-key": apiToken,
      "x-agio-timestamp": timestamp,
      "x-agio-signature": signature
    },
    body
  });

  if (!response.ok) throw new Error(`Agio returned HTTP ${response.status}`);
  const result = await response.json();
  if (result.errors?.length) throw new Error(result.errors.map((error: { message: string }) => error.message).join("; "));
  return result.data;
}

const data = await partnerQuery("query CheckConnection { __typename }");
if (data.__typename !== "Query") throw new Error("Unexpected response");
console.log("Partner API connection verified");

For example, run it with bun partner-request.ts. The output should be Partner API connection verified. Unlike a __schema introspection query, __typename requires a valid HMAC signature, so this verifies the complete request path.

A 401 means the key, signature, or timestamp was rejected. Check the environment, use milliseconds for the timestamp, and compare the signed body with the sent body. See authentication for the exact contract.

The other examples in this guide provide a GraphQL operation and JSON variables. Send them with the same partnerQuery function. A GraphQL response without errors can still contain success: false; check each operation's result before using its resource identifiers.

Get to your first funded card

1. Provision a customer organization and cardholder. Store the returned organization and cardholder identifiers.
2. Collect consent and submit an application. Choose createWallet: true for treasury-managed collateral, or supply the customer's own collateral-admin address.
3. Wait for approval, then create a virtual card with the numeric application ID.
4. Read the deposit address and fund the collateral. Use the chain and accepted token for that application.
5. Check spending power and subscribe to webhooks for application and transaction updates.

The Bun starter kit includes a provisioning script and an Express webhook receiver. Use the signing and lifecycle contracts in these pages when adapting it to your application.