@t402/cosmos

Cosmos Hub ecosystem implementation for T402 payments using native bank transfers on Noble chain.

Installation

npm install @t402/cosmos

pnpm add @t402/cosmos

yarn add @t402/cosmos

Overview

The @t402/cosmos package enables T402 payments on the Cosmos ecosystem using native USDC transfers on Noble chain. It uses the exact-direct scheme — the client executes the token transfer directly on-chain, then provides the transaction hash as proof of payment.

Key features:

Noble chain — native USDC issuance via Circle’s Cross-Chain Transfer Protocol (CCTP)
Direct settlement — client submits the transfer, no facilitator relay needed
Instant finality — Tendermint consensus provides immediate transaction finality
Low fees — typical gas cost ~0.005 USDC per transaction
Bech32 addresses — human-readable noble1... format

Supported Networks

Network	CAIP-2 ID	RPC Endpoint	REST API
Noble Mainnet	`cosmos:noble-1`	`https://noble-rpc.polkachu.com`	`https://noble-api.polkachu.com`
Noble Testnet	`cosmos:grand-1`	`https://rpc.testnet.noble.strange.love`	`https://api.testnet.noble.strange.love`

Quick Start

import { ExactDirectCosmosClient } from '@t402/cosmos/exact-direct/client'
 
const client = new ExactDirectCosmosClient({
  address: 'noble1abc...xyz',
  signAndBroadcast: async (txRaw) => {
    // Use your Cosmos wallet to sign and broadcast
    const result = await wallet.signAndBroadcast(txRaw)
    return result.transactionHash
  }
})
 
// Create payment payload (executes transfer on-chain)
const payload = await client.createPaymentPayload(2, requirements)

Client Usage

import { ExactDirectCosmosClient } from '@t402/cosmos/exact-direct/client'
 
const client = new ExactDirectCosmosClient({
  address: 'noble1ejc2c2gvk46h7kyulx9fus85vdpq0zdjwkfav0',
  signAndBroadcast: async (txRaw) => {
    // Sign and broadcast the MsgSend transaction
    const result = await wallet.signAndBroadcast(txRaw)
    return result.transactionHash
  },
  gasLimit: '200000',      // optional, default 200000
  gasPrice: '0.025uusdc'   // optional, default 0.025uusdc
})
 
// Create payment payload (executes transfer on-chain)
const payload = await client.createPaymentPayload(2, requirements)

Server Usage

import { ExactDirectCosmosServer } from '@t402/cosmos/exact-direct/server'
 
const server = new ExactDirectCosmosServer({
  rpcUrl: 'https://noble-rpc.polkachu.com',
  restUrl: 'https://noble-api.polkachu.com'
})
 
// Enhance requirements with Cosmos-specific fields
const enhanced = await server.enhancePaymentRequirements(baseRequirements)

Facilitator Usage

import { ExactDirectCosmosFacilitator } from '@t402/cosmos/exact-direct/facilitator'
 
const facilitator = new ExactDirectCosmosFacilitator({
  rpcUrl: 'https://noble-rpc.polkachu.com',
  restUrl: 'https://noble-api.polkachu.com'
})
 
// Verify the transaction hash from client
const result = await facilitator.verify(payload, requirements)
// For exact-direct, settle is a no-op (already settled by client)
const settled = await facilitator.settle(payload, requirements)

PaymentRequirements

const requirements = {
  scheme: 'exact-direct',
  network: 'cosmos:noble-1',
  amount: '1000000', // 1 USDC (6 decimals)
  asset: 'uusdc', // denomination (microUSDC)
  payTo: 'noble1ejc2c2gvk46h7kyulx9fus85vdpq0zdjwkfav0',
  maxTimeoutSeconds: 300
}

Payload Structure

interface ExactDirectCosmosPayload {
  txHash: string;    // Transaction hash (hex, no 0x prefix)
  from: string;      // noble1... sender address
  to: string;        // noble1... recipient address
  amount: string;    // Amount in uusdc (smallest unit)
  denom?: string;    // Token denomination (default: uusdc)
}

Payment Flow

Client creates a /cosmos.bank.v1beta1.MsgSend transaction
Client signs and broadcasts the transaction to Noble chain
Transaction executes with Tendermint consensus (instant finality)
Client returns the transaction hash as proof of payment
Facilitator verifies the transaction via RPC or REST API

The exact-direct scheme means the client settles the payment directly on-chain. The facilitator only verifies the transaction — it does not relay or execute it.

Token Details

Property	Value
Token	Native USDC (Circle CCTP)
Denomination	`uusdc` (micro-USDC)
Decimals	6
Facilitator Address (Mainnet)	`noble1ejc2c2gvk46h7kyulx9fus85vdpq0zdjwkfav0`
Facilitator Address (Testnet)	`noble1ejc2c2gvk46h7kyulx9fus85vdpq0zdjwkfav0`

Gas Configuration

Parameter	Value
Gas Limit	200,000
Gas Price	0.025 uusdc
Typical Fee	~0.005 USDC (5,000 uusdc)

Error Codes

Code	Description
`invalid_payload_structure`	Missing txHash, from, to, or amount
`network_mismatch`	Transaction network doesn’t match requirements
`amount_mismatch`	Transferred amount less than required
`recipient_mismatch`	Transfer recipient doesn’t match payTo
`denom_mismatch`	Token denomination doesn’t match requirements
`transaction_not_found`	Transaction hash not found on-chain
`transaction_failed`	Transaction exists but failed

Multi-SDK Examples

import { ExactDirectCosmosClient } from '@t402/cosmos/exact-direct/client'
import { t402Client } from '@t402/fetch'
import { registerExactDirectCosmosClient } from '@t402/cosmos/exact-direct/client'
 
// Setup client
const cosmosClient = new ExactDirectCosmosClient({
  address: wallet.address,
  signAndBroadcast: wallet.signAndBroadcast
})
 
// Register with t402 client
const client = new t402Client()
registerExactDirectCosmosClient(client, {
  address: wallet.address,
  signAndBroadcast: wallet.signAndBroadcast
})
 
// Make paid request
const response = await client.fetch('https://api.example.com/premium')

import "github.com/t402-io/t402/sdks/go/mechanisms/cosmos"
 
// Client
client := cosmos.NewExactDirectCosmosScheme(signer, &cosmos.ExactDirectCosmosClientConfig{
    GasLimit: "200000",
    GasPrice: "0.025uusdc",
})
payload, err := client.CreatePaymentPayload(ctx, requirements)
 
// Server
server := cosmos.NewExactDirectCosmosServer(&cosmos.ExactDirectCosmosServerConfig{
    RPCURL: "https://noble-rpc.polkachu.com",
    RestURL: "https://noble-api.polkachu.com",
})
enhanced, err := server.EnhancePaymentRequirements(ctx, requirements)
 
// Facilitator
facilitator := cosmos.NewExactDirectCosmosFacilitator(&cosmos.ExactDirectCosmosFacilitatorConfig{
    RPCURL: "https://noble-rpc.polkachu.com",
    RestURL: "https://noble-api.polkachu.com",
})
result, err := facilitator.Verify(ctx, payload, requirements)

from t402.schemes.cosmos.exact_direct.client import ExactDirectCosmosClient
from t402.schemes.cosmos.exact_direct.server import ExactDirectCosmosServer
from t402.schemes.cosmos.exact_direct.facilitator import ExactDirectCosmosFacilitator
 
# Client
client = ExactDirectCosmosClient(
    address="noble1abc...xyz",
    sign_and_broadcast=wallet.sign_and_broadcast,
    gas_limit="200000",
    gas_price="0.025uusdc"
)
payload = await client.create_payment_payload(requirements)
 
# Server
server = ExactDirectCosmosServer(
    rpc_url="https://noble-rpc.polkachu.com",
    rest_url="https://noble-api.polkachu.com"
)
enhanced = await server.enhance_payment_requirements(requirements)
 
# Facilitator
facilitator = ExactDirectCosmosFacilitator(
    rpc_url="https://noble-rpc.polkachu.com",
    rest_url="https://noble-api.polkachu.com"
)
result = await facilitator.verify(payload, requirements)

import io.t402.mechanisms.cosmos.ExactDirectCosmosClient;
import io.t402.mechanisms.cosmos.ExactDirectCosmosServer;
import io.t402.mechanisms.cosmos.ExactDirectCosmosFacilitator;
 
// Client
var client = new ExactDirectCosmosClient(
    "noble1abc...xyz",
    wallet::signAndBroadcast,
    "200000",
    "0.025uusdc"
);
var payload = client.createPaymentPayload(requirements);
 
// Server
var server = new ExactDirectCosmosServer(
    "https://noble-rpc.polkachu.com",
    "https://noble-api.polkachu.com"
);
var enhanced = server.enhancePaymentRequirements(requirements);
 
// Facilitator
var facilitator = new ExactDirectCosmosFacilitator(
    "https://noble-rpc.polkachu.com",
    "https://noble-api.polkachu.com"
);
var result = facilitator.verify(payload, requirements);

Example: Express Integration

import express from 'express'
import { paymentMiddleware } from '@t402/express'
 
const app = express()
 
app.use(paymentMiddleware({
  'GET /api/premium': {
    price: '$0.01',
    network: 'cosmos:noble-1',
    asset: 'uusdc',
    payTo: 'noble1ejc2c2gvk46h7kyulx9fus85vdpq0zdjwkfav0',
    description: 'Premium API access'
  }
}))
 
app.get('/api/premium', (req, res) => {
  res.json({ data: 'premium content' })
})
 
app.listen(3000)

Protocol Specification Facilitator API Express Middleware Fetch Client

Additional Resources

@t402/stacks @t402/btc